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About These Notes 


These notes discuss the technical aspect of the firmware and hardware of the AppleFax 
modem. It is intended to supply the information necessary to the developers to integrate the 
AppleFax modem into new environments. 
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Apple's main objective in releasing this information is to create a development environment 
for the AppleFax modem, and to ensure compatibility with third party software. The main 
sections of these notes consist of the hardware technical review, the firmware review, and 
information about the driver. Appendix B provides a hard copy of the object code 
necessary to address the driver. 


Most applications today interface with the AppleFax modem driver as if it were a standard 
printer resource. For applications such as these you are not required to make any code 
changes. Detailed information is supplied in these notes for those developers who wish to 
access the low level functions of the modem. For developers who wish this added 
functionality, the AppleFax library must be linked using the MPW linker. 


These preliminary notes do not constitute a manual and should not be considered complete 
in their present form. While every attempt has been made to verify the accuracy of the 
information presented, it is subject to change without notice. 


Supplemental Reference Documents 


In addition to these preliminary notes, it is suggested that the following publications be 
used as a source of reference: 


. 


a Inside Macintosh, Volume 2 contains information on the Apple Print Manager. 
a AppleFax User's Guide contains basic information on the user application and 
technical appendices, including a complete list of modem commands. 


a CCITT Specification T.30 “Procedures for Document Facsimile Transmisssion 
in the General Switched Telephone Network." 


Terminology 

Alert Box A message displayed on the Macintosh screen to indicate 
action. 

AFInfoSize A firmware term indicating 64 bytes 

AppleFax station The station consists of the host Macintosh, the AppleFax 
modem, any serial device attached through the auxiliary port 
on the modem, and the phone equipment attached. 

bps Bits per second 

ByteTime A firmware term indicating 1 second 

Calls Commands sent between the host computer and the attached 
AppleFax modem 

CapSize A firmware term indicating 8 bytes 

Dialog Box A box of selectable parameters displayed on the Macintosh 
screen to allow the user to set desired parameters. 

Fax Station A station containing a standard facsimile machine rather than 
an AppleFax modem. 


Fax (Facsimile) Machine A Fax machine is capable of sending/receiving graphic 
transmission over the standard telephone lines from an 
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AppleFax modem and reproducing the image for hard copy 
only (it cannot store the image like the Macintosh). 


FSK Frequency Shift Key 

G2 Fax Machine Uses an older encoding format with a reverse bit order . 

G3 Fax Machine Uses the Hoffman encoding format. 

Host computer/processor Computer directly attached to the AppleFax modem. 

IdentSize A firmware term indicating 20 bytes 

MaxLength A firmware term indicating 1200 bytes 

MPW Macintosh Programmers Workshop 

Packet A group of formatted bytes used to transmit status and data 
between stations. 

PAL Programmable Array Logic chip 

Result Codes Specific error messages transmitted via packet format. 

RenumnTime A firmware term indicating 2 seconds 

SCC Serial Channel Controller 


Software Checklist 


Before you install your AppleFax modem applications, verify the following files are on the 
3.5" disk included in your AppleFax modem seed package: 


o 
a 
Co 


a) 


AppleFax modem driver 

AppleFax applications 

FaxTest folder: contains sample applications demonstrating the use of the 
AppleFax library. 

- FaxTest.c: source code in C for the main part of the sample application. 


- FxCalls.c: source code in C to demonstrate how to make low level fax 
firmware calls. 


- FaxTest.r: resource text file for the resources of the test application. 
- FaxTest.c.o: object code for FaxTest.c. 

FxCalls.c.o: object code for FxCalls.c. 
Sanmie Fax Files folder: contains sample T4 and FaxFile formats. 


- Convert FaxFile: this is a fax file created from the received T4 file (see 
below) by using the library command FxConvertFile. 


- Receved T4: this file contains a T4 encoded image created by receiving the 
image in the AppleFax application. 

FaxLib folder: contains the MPW created linkable AppleFax library. 

- FaxLib.o: AppleFax library. 

- FaxLibr: resource text file of resources required by the library routines. 

- FaxLib.Rsrc: actual resources required by the library. 

FxIncludes folder: contains the include files required by the applications 

accessing the library 

- FaxIntf.p: PASCAL unit containing the structures and constants used by the 
AppleFax library. 

- FaxLibIntf.p: PASCAL interface file that defines the available library calls. 
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- Fax.h: C version of FaxIntf.p (you must use this file if you build the 
sample application FaxTest. 
co ACResDef folder: contains the include files needed to build the resources used 
by the library. 
- FxTypes.r: resource include file required to 'REZ' FaxLib.r. 


AppleFax Functional Overview 


This portion of the developer notes elaborates on the technical discussion given in 
Appendix F of the AppleF'ax Modem User's Guide. Figure 1 provides a more detailed 
functional block diagram. Additional technical information is also provided. 


Hardware Configuration 


The AppleFax electronics are arranged on.a 5-inch by 8-inch printed wiring board assembly 
(here after referred to as the digital module) with the fax modem logic installed piggyback 
onto the board at connector J5. The digital module contains the microprocessor, RAM and 
ROM chips, three programmable array logic (PAL) chips, Serial Channel Control (SCC) 
chip, and miscellaneous supporting logic. Also included in the hardware is an external 
power supply used to provide +12V and +5V power. A -5V regulator installed on the 
digital module board generates the -5V power. 


The digital module contains five on-board connectors labeled J1, J2, J3, and JSA/B. These 
connectors and their function are listed below: 


Connector Function 


J1 Interface to/from the host 

J2 Interface to/from pass-through port 

J3 RJ11 type connector to/from phone lines 

JD Fax modem circuitry to/from digital module 


Functional Description 


The AppleFax modem operates in one of two modes: FAX mode and the PASS- 
THROUGH mode. In FAX mode, the modem functions as a standard facsimile (fax) 
machine either in normal fax operations or in a high-speed data communications mode. In 
the PASS-THROUGH mode, the AppleFax modem is used simply to pass information 
between the attached host computer (Macintosh) and many kinds of serial devices 
connected to the auxiliary port of the modem. The following paragraphs discuss each of 
these modes in reference to the functional block diagram given in Figure 1. 


Operating in the AppleFax mode, your station can act either as the sending station, to 
initiate the facsimile transmission, or as the receiving station. As a sending station, the host 
computer initiates the facsimile operation by sending a series of commands (in firmware 
these commands are referred to as Calls) through the interface (J1) to the attached AppleFax 
modem. The commands are received by the resident microprocessor in the AppleFax 
modem, which in turn initiates the facsimile operation. The operation is begun by dialing 
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the phone number (given by the host computer) of the destination fax. Once the destination 
fax acknowledges (OK), data transmission begins. All communications between the host 
processor and the AppleFax modem are serial using RS-422 serial communication 
protocol. Information is received from the host processor on the RXD- and RXD+ lines 
which represents both polarities of the receive line. These signals are filtered and fed to the 
differential recéiver, which drives the RXDB line to the Serial Channel Controller (SCC) 
and to the address decode PAL. 


When the AppleFax modem is acting as the receiving station, its ring detection logic detects 
the incoming call and signals the PAL, which informs the microprocessor. The 
microprocessor sends the OFHK (offhook) signal to the line selector relay, which selects 
the phone line for transmission by closing two switches (see Figure 1). The phone line 
driver and receiver circuitry is used both to supply current to the phone line through the 
coupling of the audio transformer, and to act as a receiver to transfer signals from the 
phone line to the fax modem logic. The audio transformer serves as an isolator for the 
main electronics from the phone line to the driver/receiver. 


Once the modem receives the information, the data pump logic takes over. The data pump 
logic is a R96 compatible chip set that is physically mounted in piggyback fashion to the 
main digital module. This logic interfaces to the microprocessor through the data bus and 
through a synchronous bit-oriented channel to the SCC. Ultimately, the data pump is 
responsible for transmitting the serial data bits using the TXA line. The TXA line is sent 
through the driver amplifier and passed onto the audio coupler to the phone lines. 
Similarly, it receives serial bits transmitted from other stations through the RXA line. The 
data pump then sends the serial data bits to the SCC for conversion into parallel data via the 
synchronous modem data channel. 


The data pump logic contains three tone detectors and a tone generator used for tone 
signalling and detection. In the 300 bps FSK receive configuration, the presence of tones 
at preset frequencies is indicated by the pattern of sequential bits in the interface memory 
modem. This memory is read by the microprocessor. Refer to Appendix G in the 
AppleFax Modem User's Guide for a list of the tonal signal frequencies, transmitter carrier 
frequencies, and the signalling data rates. 


The data pump provides equalization functions that can be used to improve performance 
during operation over poor telephone lines. One function is the use of cable equalizers to 
optimize performance over different lengths of non-loaded cables. Also, line amplitude 
equalizer are used in the transmit and receive paths. And lastly, an automatic adaptive 
equalizer is used in the receiver circuit for V.27ter and V.29 configuration. 
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Figure 1: AppleFax Modem Functional Block Diagram 
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Firmware Technical Overview 


This section of the developer notes contains a description of the firmware that resides in the 
ROM of the AppleFax modem. Refer to Appendix C of the AppleFax Modem User's 
Guide for a list of the modem commands. 


The first function of the AppleFax modem firmware is to perform power-up self tests. 
Upon power-up of the modem, the firmware examines the contents of the first three bytes 
of the test page addresses ($4000 through $77FF). If these locations contain a jump 
instruction to $4003, the firmware will branch to address $4000. At this point, the test 
fixture code performs a comprehensive test of the modem. 


In the next phase of the power-up sequence, the firmware performs self tests on the 
modems main components listed below to determine their functionality. 


Component Functional Test 


ROM Firmware calculates the ROM checksum and compares it 
with its correct value. 

RAM Firmware performs several simple tests to ensure RAM 
functionality. . 

scc The SCC is minimally tested by the firmware. 


Data Pump Minimal functional tests performed by the firmware. 


If any of these self-tests fail, the indicator lights on the front of the AppleFax modem will 
alternately blink (four cycles per second). Upon successful completion of the self-tests, the 
modem enters the AT command mode. 


AppleFax Operating Modes 


The AppleFax modem operates in one of four firmware modes: AT Command mode, Data 
mode, Pass-Through mode, and Fax Command mode. Upon power-up, the modem will 
always enter the AT Command mode. The remaining modes are entered from the AT 
Command mode only, and exit back to that mode. Figure 2 shows the various commands 
used to enter and exit specific modes. Typically, the Pass-Through mode is entered using 
the front panel switch; however it can also be entered using the AT command, AT>. 
Exiting from the Pass-Through niode can be done using the front panel switch or the exit 
character. Each of the four modes are discussed further in the following paragraphs. The 
panel switch is operational only between the AT command mode and Pass-Through mode. 


AT Command Mode 


The AppleFax modem accepts commands sent form the host computer, or another 
AppleFax station, once it receives a specific string of characters. When one of these 
specific strings of characters is transmitted (either AT, at, A/, or a/ ), the AppleFax 
modem enters the AT Command mode and interprets all subsequent characters as 
commands from the AT command set. A complete list of these commands is contained in 
Appendix C of the AppleFax Modem User's Guide. The AppleFax modem will continue 
to interpret the characters as commands until an error occurs (such as over 64 characters 
transmitted) or until a RETURN is transmitted. The AppleFax station will return responses 
to the AT commands if you have not turned the Quiet command on. 
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Figure 2: AppleFax Modem Firmware Operational Modes 


When you first power-on the AppleFax modem it will be in the AT command mode and 
ready to accept any AT command from the AppleFax host computer. To recognize the 
transmission as commands, the AppleFax modem must first receive either an AT or at 
sequence. All subsequent transmissions will then be interpreted as AT commands. If the 
first command received is either the A/ or a/ String, the modem will interpret it as if it were 
the AT or at command string. 


At the first occurrence of an AT or at sequence, the AppleFax modem will automatically 
determine the baud rate. This baud rate will be used until the modem is turned off, or until 
any reset command is issued. 


If connection is made with another AppleFax modem using either the ATA command or 
the ATD command, your modem will enter the data mode (also referred to as the 'online’ 
mode). To exit the data mode and return to the AT command mode, you must execute the 
escape sequence. This escape sequence is either "+++AT" or "+++at". Since you typed 
the AT sequence as part of the escape code, the modem will retum to the AT command 
mode and wait for further commands. Your modem maintains its connection to the other 
AppleFax until you send an ATH command to hang up the phone. You can enter data 
mode any time prior to the ATH command by typing the ATO command. 
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Other modems that use the AT command set differ from the AppleFax modem in that the ( 
escape sequence consists of [pause]+++[pause]. Upon receiving this escape sequence, 
the modem enter the command mode and returns an OK response. To remain compatible 

with these other modems, the AppleFax modem recognizes the [pause]+++[pause] 

sequence while in the data mode, and will return the OK response. However, the modem 

will not enter the command mode uniess it detects an AT or at as the very next character 

sequence. 


Data mode 


The AppleFax modem operates in the data mode for data transmission and reception 
between fax modems. Data mode is entered only from the AT Command mode using the 
ATD, ATA, and ATO commands. To exit the data mode, use the escape sequence. 


Fax Command mode 


The Fax command mode is entered only from the AT Command mode using the AT: 
command. To exit this mode, use the fax command Reset or power down the modem. 
While in the Fax Command mode, communication with another AppleFax station, and 
sending and receiving to a fax machine are performed. Other miscellaneous operations also 
take place from this mode, such as viewing and setting register values, obtaining status, 
and getting the results of the previous command. Figure 2 shows the operations performed 
from the Fax Command mode and lists the commands associated with each operation. A 
description of these commands follows the mode discussion. 


Pass-Through mode | 


The AppleFax modem operates in the Pass-Through mode when communication is between 
the host computer and the device attached to the auxiliary port of the AppleFax modem. 
Data being transmitted from the host to the attached device passes through the modem with 
no data manipulation by the modem. The modem is used Strictly as a transmission path. 


The data lines of the two serial ports are connected by hardware circuits to allow data, at 
any rate, to be passed directly through the modem. The control lines, however, are passed 
through using software control. This causes a minute delay from the input on one port to 
the output on the other. This delay is less than 65 microseconds and should not affect the 
operation of most devices, however, some specialized interfaces might be affected. The 
signals that are delayed are listed below: 


Host Port 

GPi (7) <-- GPi (7) 
HSKO (1) <-- HSKI (2) 
HSKI(2) = --> HSKO (1) 


Entry into this mode can be done from the AT command mode using the AT> command or 
by using the modem’s front panel switch. The front panel switch is only operational from 
the AT command mode and not from the Data mode or Fax mode. Prior to using the AT> 
command, register S15 must be set to enable the command character (>). 
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To enable the Pass-Through Mode command character (>), set register S15 to a value 
greater than 256. Setting this register to a value less than 256 will disable the command. 
Use the following format to specify the exit character: 

ATSI5 = VAL 


where VAL is 256 + [exit character]. The exit character in this equation is the ASCII value 
of the character you have chosen. Register $15 has a default value of 0, which disables the 
Pass-Through mode command. It can be set with any value between 0 and 511. 


Resets 


The AppleFax modem can be reset using one of three methods depending on the mode you 
are operating in. The normal way to perform a reset is to use the Reset command 
(command number 14). This command is used by the host computer and overrides all 
other commands. If you are in the AT Command mode, you can issue the ATZ command. 
The third way to reset the modem is used in emergencies from the Fax Command mode by 
sending a string of 2-bytes containing the value '2121' (ASCTI characters !!) until they 
begin to echo back. Once you see the exclamation mark (!) being echoed back, it means the 
modem has been reset and you are in AT command mode. 


Operation of the AppleFax. 


As previously mentioned, upon initial power-up, the AppleFax modem enters the AT 
command mode. To communicate between the modem and the host computer using 
"packets" you must be in the Fax Command mode. The packets used during the 
communication are an organized method of packaging the data, commands, and status 
information for transfer. The protocol setup between the host computer and the modem 
begins with the host computer sending packets containing commands and data to the 
modem, and the modem returning packets containing status, results, and data. Each packet 
also contains checksum information to allow the detection of any transmission errors. 


If your host computer is a macintosh, use the AppleFax library to handle the packet 
protocol for you (see “AppleFax Library” paragraph later in these notes). 


The packet protocol between the modem and a host computer consists of the three types of 
packets listed below: 


c Command packet: from host to modem 
o Return packet: from modem to host (automatically sent) 
a Result packet: from modem to host (only sent when asked for) 


The host computer sends a command packet to the modem, which begins to execute the 
command. Some of the commands execute immediately and send the return packet upon 
completion. Other commands, however, take a variable length of time to execute, and 
therefore, do not send a return packet. In these cases, the host computer must monitor the 
progress of the command during execution. The progress of the command is monitored by 
sending a Status request to the modem. A Status request is a special command that is 
serviced even while another command is executing. The Status request returns information 
about the modem which includes the state of the currently executing command. The host 
computer can determine from the returned information that the command has completed its 
execution. To determine the results of the command, the host computer sends a GetResult 
command to the modem. In response, the modem returns a result packet to the host . 
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A 2-byte confirmation format is used between the host computer and the modem to confirm 
transmission. These confirmation bytes contain a value of either '0101' to indicate 
transmission received; or a value of '0202' indicating the transmission sent was erroneous, 
retransmit. An exception to this is the TransmitLine command. The AppleFax modem 
does not respond with confirmation bytes when this command is sent from the host. 


In summary, there are 3 types of packets: command packets, which cause the modem to 
begin executing a command; return packets, which some commands return immediately 
upon completion; and result packets, which the modem sends in response to a GetResult 
command. A fourth type of packet, the control packet, is used that does not conform to 
the basic packet format. 


Now that you know the basic communication protocol, let's discuss the following fax 
operations: 


Calling a fax machine or another AppleFax station 

Receiving a call from a fax machine or another AppleFax station 
Sending fax files to a fax machine 

Receiving fax files from a fax machine 

Transferring data between AppleFax stations 

Closing the connection _+ 


o0o006dmNOUhUmLNdLhULD 


The structure and contents of the command, return, and result packets for the commands 
mentioned in the following operations are given later in this document under Fax modem 
command formats’. 


Calling a Fax Machine or Another AppleFax Modem 


To call another AppleFax modem or a fax machine, the modem must be in the Fax 
command mode. Entry to the Fax Command mode is obtained only from the AT 
Command mode using the AT: command. To establish communication, the host computer 
issues the FaxDial command using the command packet format. The FaxDial command 
packet contains the following information: 


The phone number to dial 

The host computer's station identification 

Fax information (vertical resolution, transmission parameters) 
Mode: standard, or AppleFax 

Extended AppleFax identification, if applicable 


oO o0 0 80 


The Mode field specifies how the fax modem should identify itself to the target device. 
Standard tells the AppleFax modem to act just like a standard fax machine. AppleFax 
indicates the modem is to identify itself as an AppleFax modem and enter packet transfer 
mode if the other device is also an AppleFax modem. 


Issuing the FaxDial command causes the modem to dial the phone number indicated and 
wait for the phone to be answered. If the phone is answered by a fax machine or an 
AppleFax modem, the modem receives its station identification and determine its 
capabilities. The host computer issues Status requests until it is determined that the 
command has completed execution. 
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Once execution complete is determined, the host computer issues the GetResult command 
to the modem. The modem then returns the information received from the remote device in 
the form of a result packet. This packet contains the following information: 


co Was the call answered by a compatible device? 

a The answering device's station identification 

a Fax information (vertical resolution, transmission parameters) 
co Mode: standard, or AppleFax 

a Extended AppleFax identification, if applicable 


If the Mode is ‘standard’, the host computer must execute a FaxTransmit command 
following the completion of the FaxDial command. If, however, the mode is 'AppleFax’, 
the host computer must begin to execute packet transfer commands, described below. 


Receiving a Call from a Fax Machine or Another AppleFax Station 


Like the transmission operation, the AppleFax modem must be in Fax Command mode in 
order to be able to receive a call from another station. The host computer issues a 
GetRegister command to examine the number of rings that have occurred since the Fax 
Command mode was entered, or since the SetRegister command was issued to reset the 
register. The number of rings is contained in modem register 1. Once the host computer 
determines that enough rings have occurred, it issues the FaxAnswer command. This 
command functions similar to the FaxDial command except that it connects immediately to 
the phone line rather than dialing a number first. The modem passes on the information 
received from the sending station in a result packet when the host computer issues a 
GetResult command. 


If the Mode returned is set to standard, the host computer must immediately execute a 
FaxReceive command. If the mode is AppleFax, the controller begins to execute packet 
transfer commands, described below. 


Sending an Image to a Fax Machine: 


Once connection to the target fax is established and the FaxTransmit command is issued, 
the host computer executes a TransmitLine command for each line of graphics data from the 
image. The controller must prepare each line of raw graphics data before sending it 
according to the current transmission mode. If the target is a group 3 fax machine, the data 
must be converted to Huffman encoded run length form as specified by CCITT 
specification T.4. If the target is a group 2 fax machine, the data is non-encoded and 
converted to lines of exactly 1728 bits (216 bytes). After the last line of data for a page has 
been sent, a TransmitEnd command must be executed. TransmitEnd returns a flag to 
indicate whether or not the quality of the received image was acceptable. If the quality was 
unacceptable, the host computer may retransmit the image, perhaps forcing the modem to 
use a lower data rate. For multiple page documents, the host computer issues another 
FaxTransmit command and repeats the process. 


To better illustrate the method by which fax data is transmitted, some sample procedures 


are provided on the 3.5 disk supplied with your seed package. These samples are 
contained in the Fax File folder on the disk. 
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Receiving an Image From a Fax Machine: 


When connection is made with a sending device, the host computer issues a FaxReceive 
command to the modem to determine if a page is available to be received. If a page is 
available, the controller immediately begins executing ReceiveBuffer commands, which tell 
the modem to return blocks of compressed graphics data to the host computer. 
ReceiveBuffer commands must be executed often enough to keep up with the average rate 
of data coming from the transmitting station. If the sending fax is a group 3 machine, the 
data must be converted from Huffman encoded run length form as specified by CCITT 
specification T.4. If the sending fax is a group 2 machine, the data is non-encoded and 
converted to lines of exactly 1728 bits (216 bytes). 


ReceiveBuffer sets a flag in the return packet when all of the image data for a page has been 
received. When the host computer detects this flag, it executes a ReceiveEnd command. 
This command tells the modem whether the quality of the received image was acceptable. 

It then issues another ReceiveBuffer command to determine if more pages are available, 
and if so, it repeats the receive process. 


To better illustrate the method by which fax data is captured during reception, stored in a 
temporary file, and then converted by the library, some sample procedures are provided in 
Appendix C of these Preliminary Notes. ~ 


Transferring Data Between AppleFax Stations 


When communication is between two AppleFax stations, packet transfer commands are 
used to exchange data between the two modems. These commands are the TransmitPacket 
and ReceivePacket commands. They allow the host computer to send data to and receive 
data from the other AppleFax station in packet format. 


Closing a Connection 


When communication between the host computer and the target station is complete, the 
Disconnect command is issued by the controller to terminate the transmission. 


AppleFax Modem Command Formats 


As shown in Figure 2, communication and transmission operations are accomplished from 
the Fax Command mode. Each of the operations performed under the Fax Command mode 
require certain commands with specific packet formats. Before we get into the command 
formats, it is helpful to understand the definitions of certain words and phases used 
throughout the discussion: 


Tem Meaning 
ByteTime 1 second. 
ReturnTime 2 seconds. 
MaxLength 1800 bytes. 
CapSize 8 bytes. 
IdentSize 20 bytes. 
AFinfoSize 64 bytes. 
PNumSize 64 bytes. 
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Definition of Packet Formats 
To summarize packets, it is important to remember there are three types of packets; 
command packets, return packets, and result packets. All three packets have the same 


basic format, shown in Figure 3. Each field of the format is discussed following the 
figure. _ 


Type Length Checksum 1 Data Checksum 2 
1 Byte 2 Bytes 1 Byte n Bytes 2 Bytes 


Figure 3: Packet Format 


Type This 1 byte field contains a value indicating the type of packet being 
transmitted: 
Command packet = command number + $80 (128) 
Result packet = command number + $CO (192) 
Return packet = command number + $40 (64) 

Length The 2 byte Length field contains a value indicating the number of the 
actual data bytes. This value must not exceed the MaxLength of 1800 
bytes. 


Checksum1 This 1 byte field contains a value that is the sum of the first three bytes 
. of the packet. It is provided to verify that the length field has been 
sheds transmitted before an attempt is made to read the rest of the 
packet. 


Data Data is a variable field that contains the actual data being transmitted. 
The maximum number of bytes in this field is 1800 bytes (MaxLength). 


Checksum2 This 2 byte field contains the sum of the data bytes in the data field. If 
there is no data in the data field, this value is zero. 


Commands are sent between the fax modem and the host processor using the format 


shown in Figure 3. Each of the commands is assigned a command number, as listed on 
the following page: 
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Number Command ‘< 


0 Status 
1 FaxDial 
2 FaxAnswer 
5 FaxTransmit 
4 TransmitLine 
5 TransmitEnd 
6 FaxReceive 
t ReceiveBuffer 
8 ReceiveEnd 
9 TransmitPacket 
10 ReceivePacket 
11 Disconnect 
12 SetRegister 
13 GetRegister 
14 Reset 
15 Not Used 
16 Version 
17 GetResult 
18 PickUp 
19 HangUp : 
Result Codes 
The result field of the basic packet protocol format is used in all result packets and in the . 
return packet of the Status command. This 1 byte field contains a code indicating the ( 


current status. These result codes, their meaning, the hex value, and the decimal value are 
listed below: 


Hex Decimal 
Result Code Value Value Meaning 
Executing $01 (1) Command still executing. 
NoErr $00 (0) Command execution successful. 
InvalidExr SEC (-20) Command invalid and cannot be executed. 
TOutErr $SFF : (-1) A time out occurred with the remote device. 
CommErr SFE (-2) Communication error occurred with remote 

device. 

IncompE:zr $FD (-3) Remote device is incompatible. 
NolmageErr $F6 (-10) No image is available to be received. 
SystemErr SF5 (-11) Modem has had a fatal system error. 
TooLongErr $F4 (-12) Modem received packet that was too long. 
OverFlowErr $F3 (-13) Some image data lost due to buffer overflow. 
LongStrEr $E2 (-30) A string in the command is too long. 


All of the commands are transmitted and received using the packet format shown in Figure 
3. The data field of that format differs for each command. The following pages contain 
descriptions of the commands along with a description of the contents of the data field for 
the three types of packets. 
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Status Command (command number 0) 


The Status command is a specialized command that can be serviced by the modem while 
another command is executing. The command is sent in the protocol format shown in 
Figure 3. The contents of the data field of that format is given below for each of the 
packet types: 


Command Packet Data 


Empty (0 bytes) 


Return Packet Data 
Resuit Command Status 
1 Byte 1 Byte 1 Byte 


Result If the command indicated in the command byte has not completed 
execution, the result byte contains the result code Executing, $01 (1). 
However, if the command has completed execution, the result byte 
contains the result value of the last command. Issue the GetResult 
command to obtain the command's complete results. 


Command The command byte contains the command number of the currently 
executing command, or the last command executed. If no command 
has been executed, $FF (-1) is returned. 


Status The status byte is used to indicate if data transmission is complete or if 
there is still more data to be transmitted. When the Transmit Busy bit, 
bit O of the status byte, is set to 1, it indicates there is still data to be 
transmitted from the AppleFax modems internal bufffers to the remote 
device. When set to 0, it indicates that data transmission is complete. 
Bits 7 - 1 are undefined. 


Result Packet Data 


The Status command does not affect the result buffer. 
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FaxDial Command (command number 1) 


The FaxDial command is used by the host computer to tell the modem to dial the target 
station. This command contains the following information in its data field: 


Command Packet Data 
ident Capabilities Mode | AFiRec 
n Bytes n Bytes 1 Byte n Bytes 


Phone Number This is a variable length field containing the phone number of the target 
station. Its format consists of a length byte followed by a string 
containing the phone number and any special symbols defined under 
the ATD modem command in Appendix C of the AppleFax Modem 
User's Guide. The length of this field must not exceed the 
PNumberSize (64 bytes). 


Ident This is a variable oe field containing the host computer 
identification string. The format of this field begins with a length byte 
followed by a string composed of spaces and digits. Its length must 
not exceed the IdentSize (20 bytes). 


Capabilities This is a variable length field that contains a string of data preceded by 
a length byte. The string of data describes the host computer and has 
the format of T.30's DCS packet. The length of this field must not 
exceed CapSize (8 bytes). See Appendix A for a description of the 
contents of the data string bytes. 


PhoneNum 
n Bytes 


Mode This is a 1 byte field that specifies either Standard or AppleFax mode 
for the host computer. The values are: 
Standard = 0 
AppleFax = 2 

AFiRec This is a variable length field that specifies the host computer's 


AppleFax identification to the remote device. It contains a string 
preceded by a length byte, and must not exceed AFInfoSize (64 bytes). 
This field is user defined for such things as version numbers. 


Return Packet Data 


FaxDial is not executed immediately and therefore does not have a return packet. The host 
computer must monitor this command using the Status command in order to know when 
to get the result data using the GetResult Data command 
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Result Packet Data 


Result ident ResultCap Mode AFiRec 
1 Byte n Bytes n Bytes 1 Byte n Bytes 


Result 


Ident 


ResultCap 


Mode 


AFTRec 
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This is a 1 byte field containing one of the following result codes: 
Code Meaning. 

NoErr Command successfully executed. 

InvalidErr | Command is invalid and cannot be executed. 

TOutErr A time out occurred. 

CommeEnrr Communication error occurred with the remote device. 


IncompErr The remote device is incompatible. 
SystemErr The modem has had a fatal system error. 


This is a variable length field containing the target device identification 
string. The format of this field begins with a length byte followed by a 
string composed of spaces and digits. Its length must not exceed the 
IdentSize (20 bytes). 


This is a variable length field that contains a string of data preceded by 
a length byte. This field contains the result obtained when the 
AppleFax modem compares the capabilities designated in the command 
packet with the capabilities of the target device and selects the 
appropriate mode. It has the format of T.30's DCS packet. See 
Appendix A for a description of the contents of the data string bytes. 


This is a 1 byte field that returns the mode selected by the modem when 
it compared the capabilities of the two devices. AppleFax mode is 
returned only when both devices are AppleFax modems. 


This is a variable length field that specifies the host computer's 
AppleFax identification to the remote device. It contains a string 
preceded by a length byte, and must not exceed AFInfoSize (64 bytes). 
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FaxAnswer Command (command number 2) 


This command is issued to the modem to cause it to answer the phone and establish a 
connection with the transmitting station. The command parameters and its return values 
are the same as-the FaxDial command. 


Command Packet Data 


ident Capabilities Mode AFiRec 
n Bytes n Bytes 1 Byte n Bytes 
Ident This is a variable length field containing the host computer 


identification string. The format of this field begins with a length byte 
followed by a string composed of spaces and digits. Its length must 
not exceed the IdentSize (20 bytes). 


Capabilities This is a variable length field that contains a string of data preceded by 
a length byte. The string of data describes the host computer and had 
the format of T.30's DCS packet. The length of this field must not 
exceed CapSize (8 bytes). See Appendix A for a description of the 
contents of the data string bytes. 


Mode This is a 1 byte field that specifies either Standard or AppleFax mode 
for the host computer. The values are: 
Standard = 0 
AppleFax = 2 

AFTRec This is a variable length field that specifies the host computer's 


AppleFax identification to the remote device. It contains a string 
preceded by a length byte, and must not exceed AFInfoSize (64 bytes). 
This field is user defined for such things as version numbers. 


Return Packet Data : 
FaxAnswer does not have a return packet. 


Result Packet Data 


Result Ident ResultCap Mode AFIRec 
1 Byte n Bytes n Bytes 1 Byte n Bytes 


Result This is a 1 byte field containing one of the following result codes: 
Code Meaning. 
NoErr Command successfully executed. 
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Ident 


ResultCap 


Mode 


AFTIRec 
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InvalidErr | Command is invalid and cannot be executed. 

TOutErr A time out occurred. 

CommeErr Communication error occurred with the remote device. 
IncompErr The remote device is incompatible. 

SystemErr The modem has had a fatal system error. 


This is a variable length field containing the target device identification 
string. The format of this field begins with a length byte followed by a 
string composed of spaces and digits. Its length must not exceed the 
IdentSize (20 bytes). 


This is a variable length field that contains a string of data preceded by 
a length byte. This field contains the result obtained when the 
AppleFax modem compares the capabilities designated in the command 
packet with the capabilities of the target device and selects the 
appropriate mode. It has the format of T.30's DCS packet. See 
Appendix A for a description of the contents of the data string bytes. 


This is a 1 byte field that returns the mode selected by the modem when 
it compared the capabilities of the two devices. AppleFax mode is 
returned only when both devices are AppleFax modems. 


This is a variable length field that specifies the host computer's 
AppleFax identification to the remote device. It contains a string 
preceded by a length byte, and must not exceed AFInfoSize (64 bytes). 
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FaxTransmit Command (command number 3) 


The FaxTransmit command is issued by the host computer within 35 seconds of the 
FaxDial command if the mode is set to Standard. This command prepares the AppleFax 
modem to transmit a page of graphics data to the target device. 


Command Packet Data 
None (0 bytes) 


Return Packet Data 
FaxTransmit does not have a return packet. 


Result Packet Data 


The data field in the result packet contains 1 byte of result information. This 1-byte field 
contains one of the following result codes: 


Code_ Meaning. 

NoErr Command successfully executed. 

InvalidErr | Command is invalid and cannot be executed. 

TOutErr A time out occurred. 

CommeErr Communication error occurred with the remote device. 
SystemErr The modem has had a fatal system error. 
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TransmitLine Command (command number 4) 


After the issuance of a FaxTransmit command, the host computer issues a TransmitLine 
command for each line of raw graphics data to be sent. This command sends a line of data 
from the host computer to the AppleFax modem for transmission to the target station. The 
TransmitLine command is the only command that does not send confirmation bytes back 
to the host. 


Command Packet Data 


Length Data 
2 Bytes n Bytes 
Length This is a 2 byte field containing the number of bytes in the following 
variable length data field. 
Data This is a variable length data field containing the raw graphics data to 
be transmitted. 


Return Packet Data 
TransmitLine does not have a return packet. 


Result Packet Data 


The data field in the result packet contains 1 byte of result information. The possible result 
data are: 


Code. Meaning. 


NoErr Command successfully executed. 

InvalidErr © Command is invalid and cannot be executed. 

TOutErr _A time out occurred. 

CommErr ~ Communication error occurred with the remote device. 
SystemErr The modem has had a fatal system error. 
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TransmitEnd Command (command number §) 


This command is issued by the host computer to terminate the transmission of a graphic 
image. 


Command Packet Data 


This data field consists of 1 byte of data indicating the last page was transmitted. If the 
value of this field is 1, the last page of data was transmitted. If this value is 0, it indicates 
more transmissions are to come. 


Return Packet Data 
TransmitEnd does not have a return packet. 


Result Packet Data 


Result Quality 
1 Byte 1 Byte 
Result ' The Result field contains one of the following result codes: 


Code Meaning 


NoErr Command successfully executed. 

InvalidErr | Command is invalid and cannot be executed. 

TOutErr A time out occurred. 

CommErr Communication error occurred with the remote device. 
SystemErr The modem has had a fatal system error. 


Quality This 1-byte filed contains a value that indicates the quality of the 
transmission. A value of 1 indicates the image received at the target 
station is acceptable. A value of 0 indicates the quality was poor and 
retransmission is required, possibly at a lower baud rate. 
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FaxReceive Command (command number 6) 


The FaxReceive command is issued by the host computer to prepare the AppleFax modem 
to accept a page of graphics data from the sending station. 


Command Packet Data 
None (0 bytes) 


Return Packet Data 
FaxReceive does not have a return packet. 


Result Packet Data 


The data field in the result packet contains 1 byte of result information. The possible result 
data are: 


ode Meaning 


NoErr Command successfully executed. 

InvalidErr | Command is invalid and cannot be executed. 

TOutErr A time out occurred. 

CommErr Communication error occurred with the remote device. 
NolmageErr No image is available to be received. 

SystemErr The modem has had a fatal system error. 
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ReceiveBuffer Command (command number 7) 


The FaxReceive command return packet indicates whether or not a page of data is 
available. If the rerurn packet indicates a page is available, the host computer must execute 
ReceiveBuffer commands to begin transferring blocks of data from the modem buffer to 
the host computer. The ReceiveBuffer command must be executed often enough to keep 
up with the average rate of data coming from the transmitting station. If ReceiveBuffer is 
not issued often enough, you will receive the OverFlowErr code indicating that data has 
been lost. 


Command Packet Data 


The data field of the command packet consists of one 2-byte field used to indicate the 
number of bytes in the modem’s receive buffer that are to be transferred to the host 
computer. The actual amount of data sent is indicated in the return packet data field. 


Return Packet Data 


Result Done Length Data 
1 Byte 1 Byte 2 Bytes “n Bytes 
Result This 1 byte field consists of result information. The possible result 
data are: 
Code Meaning. 
NoErr Command successfully executed. 


InvalidErr © Command is invalid and cannot be executed. 

TOutEr A time out occurred. 

CommEn:r Communication error occurred with the remote device. 
SystemErr The modem has had a fatal system error. 
OverFlowErr Some data has been lost due to buffer overflow 


Done This 1 byte field indicates if the current transmission is the last data 
transfer of the current image from the modem receive buffer. If it is the 
last transmission, the value of this field is 1. If this is not the last 
transmission, the value is 0. 


Length This 2 byte field contains a value indicating the length of the variable 
data field that follows. 

Data This is a variable length field containing the actual data being sent to the 
host computer. 


Result Packet Data 


| Resuit Bone 
1 Byte 1 Byte 


Result Same as Return packet data. 
Done Same as Return packet data. 
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ReceiveEnd Command (command number 8) 


When the host computer detects the Done flag set in the return packet of the ReceiveBuffer 
command, it executes a ReceiveEnd command to inform the modem whether or not the 
quality of the transmission is acceptable. 


Command Packet Data 


This field consists of 1 byte indicating the quality of the transmission. A value of | tells 
the modem the quality is acceptable. A value of 0 indicates the quality was not acceptable 
and a retransmission at a lower baud rate is necessary. 


Return Packet Data 
ReceiveEnd does not have a return packet. 


Result Packet Data : 


The data field in the result packet contains 1 byte of result information. The possible result 
data are: 


Code Meaning 


NoErr Command successfully executed. 

InvalidErr § Command is invalid and cannot be executed. 

TOutErr A time out occurred. 

CommErr Communication error occurred with the remote device. 
SystemErr The modem has had a fatal system error. 
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TransmitPacket Command (command number 9) 


When both the receiving and sending stations are AppleFax stations, the host computer 
issues the TransmitPacket and ReceivePacket commands to begin data transfer from one 
station to the ather. 


Command Packet Data 


Length ) Data 
2 Bytes n Bytes 
Length This 2 byte field contains a value that indicates the number of bytes in 
the following variable length data field. 
Data This variable length field contains data that is to be transmitted from the 


host computer to the other AppleFax station. 


s 


Return Packet Data 
TransmitPacket does not have a return packet. 


Result Packet Data 
The data field in the result packet contains 1 byte of result information. The possible result 


codes are: 
Code Meaning. 
NoErr Command successfully executed. 


InvalidErr |§ Command is invalid and cannot be executed. 

TOutErr A time out occurred. 

CommErr § Communication error occurred with the remote device. 
SystemErr The modem has had a fatal system error. 
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ReceivePacket Command (command number 10) 


When the modem receives a packet of data from another AppleFax station, execution of 
the ReceivePacket command will transfer the packet to the host computer. 


Command Packet Data 
None (0 bytes) 


Return Packet Data 
Result Length Data 
1 Byte 2 Bytes n Bytes 


Result The result field contains 1 byte of result information containing one of 
the following possible result codes: 


Code. Meaning. 

NoErr Command successfully executed. 

InvalidErr © Command is invalid and cannot be executed. 

TOutErr A time out occurred. 

CommErr § Communication error occurred with the remote device. 
IncompErr The remote device is incompatible. 

SystemErr The modem has had a fatal system error. 


Length This is a 2 byte field containing a value that indicates the number of 
data bytes contained in the following variable length data field. If no 
packets are available, the value of this field is zero. 


Data This variable length field contains the data from the remote AppleFax 
Station. 


Result Packet Data 
Same as the Return result field. 


9/29/87 AppleFax Modem Preliminary Notes 2) 


Disconnect Command (command number 11) 


When communication between the host computer and the target station is complete, the 
host computer issues a Disconnect command to close the connection and hang up the 
phone. 


Command Packet Data 
None (0 bytes) 


Return Packet Data 
Disconnect does not have a return packet. 


Result Packet Data 


The data field in the result packet contains 1 byte of result information. The possible result 
data are: 


Code Meaning. 

NoErr Command successfully executed. 

InvalidErr © Command is invalid and cannot be executed. 

TOutErr A time out occurred. 

CommErr Communication error occurred with the remote device. 
SystemErr The modem has had a fatal system error. 
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SetRegister Command (command number 12) 

This command is used to set the value of the modem register indicated in the register field 
of the command packet. Refer to Appendix C of the AppleFax Modem User's Guide for a 
list of the registers. 


Command Packet Data 


Register Value 
1 Byte 2 Bytes 


Register The value of this 1 byte field indicates the number of the register to be 
set. 
Value This 2 byte field contains the value the register is to be set to. The high 


order byte is first, the low order byte second. 


Return Packet Data 


The data field in the result packet contains 1 byte of result information. The possible result 


codes are: ; 
Code_ Meaning. 


NoErr Command successfully executed. 
InvalidErr | Command is invalid and cannot be executed. 
SystemErr The modem has had a fatal system error. 


Result Packet Data 


Same as Return packet data field. 
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Reset Command (command number 14) 
This command is used by the host computer to reset the modem. This command overrides 


all other commands and will be executed even if another command is in process. The 
Reset command has no return or result packets. 


Command Packet Data 


None (0 bytes) 


Return Packet Data 


Reset has no return packet. 


Result Packet Data 


Not applicable: this command resets the modem before the result can be read. 
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GetRegister Command (command number 13) 


This command is used to get the value of the modem register indicated in the register field 
of the command packet. Refer to Appendix C of the AppleFax Modem User's Guide for a 
list of the registers. 

Command Packet Data 

The data field in this packet contains one 1-byte field that indicates the register number to 
be polled. 


Return Packet Data 
Result Value 
1 Byte 2 Bytes 


Result The data field in the return packet contains 1 byte of result information. 
The possible result codes are: 


Code Meani 


NoErr Command successfully executed. 
InvalidErr © Command is invalid and cannot be executed. 
SystemErr The modem has had a fatal system error. 


Value This 2 byte field contains the value of the register indicated in the 
command packet. It is returned high byte first, low byte second. 


Result Packet Data 


Same as Return packet fields. 


AppleFax Modem Preliminary Notes 9/29/87 


Version Command (command number 16) 


The version command is used to provide the current ROM release information. 


Command Packet Data 


None (0 bytes) 


Return Packet Data 


Result ROM ROM 
Release | Version 
1 Byte 1 Byte 1 Byte 
Result This 1 byte field always contains the result code NoErr. 


ROM Release This 1 byte field contains the current ROM release level. 


ROM Version This 1 byte field contains the current version of the ROM release level. 


Result Packet Data 


The Result packet format is the same as the Return packet format. 
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GetResult Command (command number 17) 


The GetResult command is a special command that is issued by the host computer to get 
the result data of the last completed command. The Command Packet Data field is empty. 
The Return Packet of the GetResult command contains the Result packet of the last 
completed command. The GetResult command does not effect the result buffer, therefore, 
the Result Packet Data is not used. Prior to executing the GetResult command, issue the 
Status command to ensure the previous command has completed. 
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PickUp Command (command number 18) 

The PickUp command is used to connect to the phone lines (for example, ‘pick up the 
phone’) and has no effect on data transfer. This command is normally used in conjunction 
with the HangUp command (discussed next) to ignore incoming calls. 


Command Packet Data 


None (0 bytes) 


Return Packet Data 


PickUp has no return packet. 


Result Packet Data 


The Result packet contains a 1 byte Result field that always contains the result code 
NoErr. : 


a 
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HangUp Command (command number 19) 


The HangUp command is used to disconnect from the phone lines . 


Command Packet Data 


None (0 bytes) 


Return Packet Data 


HangUp has no return packet. 
Result Packet Data 


The Result packet contains a 1 byte Result field that always contains the result code 
NoErr. 
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Modem Driver Technical Overview 


This section of the developer notes describes the user interface and functions of the 
software for the AppleFax modem. 


The AppleFax modem driver will function only on the Macintosh 512 with enhanced 
ROMs, the Macintosh Plus, the Macintosh I, and the Macintosh SE computers. The 
driver supports both the group 2 and group 3 facsimile machines. If a target fax has both 
the group 2 and group 3 capabilities, the driver automatically selects group 3. For group 3 
fax machines, the modem driver supports one dimensional T4 run length encoding. The 
pixel width of a scan line for both group 2 and group 3 is 1728 bits. 


The AppleFax modem driver supports the standard high-level print manager and the low- 
level print manager. All of the high-level print manager functions supported are listed in 
Inside Macintosh, volume 2. The difference between those functions listed and the driver 
is that the modem driver always spools temporary print files to the disk while telling the 
calling application that it is in draft mode. The mandatory spooling is necessary to avoid 
data starvation problems. This means that the size of the document to be transmitted is 
limited to the available diskette space. The draft mode is used so that the application does 
not open and close the driver for every page. 


The modem driver also supports all of the’ low-level access calls, listed in Inside- : 
Macintosh, volume 2, in order to support those applications that make low-level driver Es 
calls, such as MacPaint. 


The AppleFax driver does not support text streaming (transmission of ASCTI text 

characters), Postscript, or PrGeneral commands. ( 
User interface ' | 
The user interface of the AppleFax modem driver utilizes three types of dialog boxes: 


a Style dialog 
a Job dialog 
a Set-Up dialog 


Throughout the descriptions of the dialog boxes, all selectable option fields are referred to 
as option. All action oriented buttons, such as Send, Cancel, Open, and such are referred 
to as buttons. Descriptions of the different operations within these dialog boxes are in 
Chapter 2 of the AppleF ax Modem User's Guide. 


Style Dialog 


The Style dialog allows you to specify the imaging style of the transmitted document prior 
to transmission. Figure 4 shows the Style dialog box. 
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Fax Modem ai 


Paper: @US Letter O fA4 Letter 


-—OUS Legal © International Fanfold Cancel | 
© Computer Paper 


Orientation Special Effects: @No Reduction 
© 33 % Reduction 
© 66 % Reduction 


Figure 4: Style Dialog Box 


Following is a description of the options in the Style dialog box: 


Paper The same five paper size options available for the Imagewniter are 
also available for the AppleFax: 
° US Letter 8" x 11" 
¢ US Legal 8" x 14" 
° A4 Letter 8" x 11.67" 
¢ International Fanfold 8" x 12" 
¢ Computer Paper 8" x 11" 


The AppleFax modem driver currently supports the transmission 
mode of 1728 pixel width. Eventhough fax machines image at 200 
dpi (dots per inch), the AppleFax images at 216 dpi. This is due to 
the fact that the Macintosh screen is 72 dpi (dots per inch), and 216 
is the nearest even multiple of 72. The 216 dpi was chosen over the 
normal 200 dpi due to the bad effects, including staircasing, that 
occur when fractional image conversion takes place. Thus, an 11- 
inch document will be 11.88 inches after transmission; an 8-inch 
wide document will be 8.64 inches wide after transmission; and so 
on. 


Orientation The Orientation option allows you to specify the layout, upright or 


sideways, of your document prior to transmission. 


Special Effects The Special Effects option allows you the ability to specify one of 
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three image sizes prior to transmission. So that the images to be 
transmitted are the highest possible quality, the values for reduction 
are determined by multiplying the Macintosh screen resolution by an 
even amount. For example, the three immage sizes are 


¢ No Reduction 
© 33% (72 dpi * 2) 
© 66% (72 dpi* 1) 


AppleFax Modem Preliminary Notes x 


Job Dialog 


The Job dialog box is used to specify not only quality and quantity of the transmission, but 
also the destination phone number and an address book that contains a list of fax locations 
and numbers. Figure 5 shows the format of the job dialog box. 


AppleFax™ Resource 


Page Range: @All © From: = To: [| 


Address book: Press ‘Open’ to get an address book... 
@ Auto dial 
© Manual dial 


Dial number: 5555 F 


Figure 5: Job Dialog Box 


Save File 


slau 


Following is a description of the Job dialog box options: 


Quality The Quality option allows you to specify the vertical resolution of 
either 200 Ipi (lines per inch) or 100 Ipi. These options are 
represented as Best and Faster, respectively, in the dialog box. The 
100 Ipi vertical resolution is accomplished by transmitting only 
every other line to the target station. This method takes 
approximately half the transmission time as the 200 lpi method. 


Page Range The Page Range option is the same as that of the Imagewriter printer 
in that it allows you to specify all pages of a document for 
transmission or a range of pages within a document. 


Auto dial Selection of the Auto Dial option signals the driver to dial and 
connect with the target fax station automatically by using the number 
listed in the Dial number field when the Send button is clicked. 

Note that this option is mutually exclusive with the Manual dial 
option. 


Manual dial Selection of the Manual Dial option signals the driver to call up the 
dialog box (shown in Figure 6) that tells you to dial the target fax 
station manually and to click the Send button when a carrier tone is 
detected. Note that this option is mutually exclusive with the Auto 
dial option. 
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Manually dial the target fax machine's 
phone number. Wait for the tone and press ce 


__ the OK Button. 


Figure 6: Manual dial dialog box 


Dial number Selection of this field automatically selects the Auto dial option. The 
Dial Number field is the one you use to enter the telephone number 
of the target fax station. The field is 64 characters long and will 
accept digits 0 through 9 and the following characters: ,()-tT p P 
#*. For more information on these special characters, refer to 
Appendix C in the AppleFax Modem User's Guide. The characters 
t, T, p, and P are used to designate pulse or tone dialing. Including 
one of these characters at the beginning of the number string will 
override the option’ setting in the Options dialog box discussed later. 


Address book The address book field contains a list of names and numbers created 
by the AppleFax application. The driver uses the address book as a 
read only source of phone numbers. If you click on an entry in the 
address book, the number will be automatically entered into the Dial 
number field. Once in that field, the number can be edited, if 
necessary. Any changes to the number while in the Dial number 
field will not change the entry in the address book. To open an 
address book, click the Open button in the dialog box. 


Send The Send button is action-oriented in that when it is clicked or when 
the Return or Enter keys on the keyboard are pressed, all selected 
options in the dialog box are accepted by the driver and the 
document is transmitted. 


Save file Save file is an action-oriented button that is used to activate the 
standard Put File dialog box. This dialog box allows you to save 
the image generated by the driver in a specified destination file or 
folder. Clicking the Send button in the standard Put File dialog box 
will create a fax file and exit the job dialog box. Clicking the Cancel 
button in the Put File dialog box will return you to the job dialog 
box. 


Cancel The Cancel button is action-oriented in that it will ignore any options 


selected in the job dialog box and exit the fax operation being 
performed. 
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Open 


Set up 


Help 


Open is an action-oriented button that invokes the standard Get file 
dialog box (shown in Figure 7). The Get File dialog box lists the 
available address book files that are created by the AppleFax 
application. The address books contain commonly used names and 
numbers of frequently called fax stations. Clicking the desired 

— address book in the Get File dialog box will open that book into the 
address book field of the Job dialog box. 


Oi -myfiddresses. ; 


Figure 7: Get file dialog box 


The Set Up button is used to invoke the Set Up dialog box, which is 
discussed in the following paragraphs. The Set Up dialog box 
allows you to specify the set up defaults information for a fax 
transmission. 

The action-oriented Help button calls up the Help dialog box that 


briefly describes the controls in the job dialog box. The Help dialog 
box is shown in Figure 8. 
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The Print Dialog lets you set Fax Modem print options. 


First, designate the desired print quality and page range. Nent enter 
the phone number of the device to which you want to send the fax in 
the ‘Dial number' edit box. Hit the ‘Send’ button to start transmission. 


To save a Fax File for later transmission, press the ‘Save File’ button 
and specify the file name and folder in the ‘Save’ dialog. 


For manual dialing, set the ‘Manual dial’ radio button, press the ‘Send’ 
button, and wait. After the document is made ready for Fax 
transmission, a dialog will be displayed that will inform you to dial 
the number of the device that you want to contact. When you hear 
the tone press the ‘OK’ button to connect with the device. 


Press the ‘Open’ button to access an address book. Clicking on an 
entry in the scrollable address book list will copy the entry's phone 
number to the ‘Dial number’ edit box. 


Press the ‘Set up’ button to specify default Fax options, such as pulse 
or tone dialing. 


Figure 8: Help Dialog Box 


Set Up Dialog 


As mentioned, the set up dialog box is entered by clicking the Set Up button in the job 
dialog box. The Set Up dialog box allows you to specify various fax-related set ups, such 
as the number of redial attempts, dialing mode, and a station ID number. Figure 9 shows 
the Set Up dialog box. 


AppleFan™ Resource Setup YBN 
Dialing Mode: @Tone (© Pulse Redials: fo | 


Your phone # | 408 555-1212 


i Send Station ID message 


Station 1D | From: Allen The Bold Fax 


Figure 9: Set Up Dialog Box 
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Following is a description of the Set Up dialog options: 


ID Number 


Redials 


Use station ID 


Dialing mode 


Station ID 


Error Listing 


The ID Number option field usually contains the phone number of 
the AppleFax station. This field is used to identify itself after 
connection to the target fax is completed. This message string can 
be edited. 


The Redial option field allows you to specify the number of times 
you wish the AppleFax modem to attempt a redial of the target fax 
station. 


This option field allows you to specify whether or not the driver is 
to use the text contained in the Station ID field as an identification 
string across the top of every page transmitted. The default value of 
this field is ON. The format of the identification string is as follows: 


Station ID St’ MMM DD, YY,XX:XX Page Y 


Where Station ID Srr is the string contained in the station ID field of 
the Set Up dialog box. MMM DD, YY is the current date, XX:XX 
is the current time, and Page Y is the absolute page number. The 
date and time fields are obtained from the standard Macintosh 
international utilities [UDateString and IUTimeString. The time 
string used does not include seconds. 


The Dialing mode option field allows you to specify the default 
dialing mode of pulse dialing or tone dialing. If neither of the letter 
options p / P ort/ T is specifed in the number string field of the Job 
dialog box, the setting of this field will determine the dialing mode. 


This option field can be edited to specify any station ID string you 
wish to have printed on transmitted pages. 


The AppleFax modem errors codes can be put into three catigories: 


o0 0 


Errors that cause the AppleFax modem not to respond to AT commands 
Errors reported by the application 
Errors reported by the modem driver 


Each of these are discussed in the following paragraphs. When errors do occur, reset the 
modem using the FxCmdOpen command. 


No Response Alert 


If the AppleFax modem does not respond within 5 seconds after the AT initiate phase at the 
beginning of the transmission, the No response alert box is invoked (see Figure 10). This 
action indicates that the driver cannot communicate to the modem. The user can then 
attempt to reconnect or quit the application. 


AppleFax Modem Preliminary Notes 9/29/87 


ett 


the connection and selection. Click 0K to 


__ continue, Cancel to terminate printing. 


ip The Fax Modem is not responding. Check foc 


Figure 10: No Response Alert Box 


Error Numbers 


Error numbers are returned to the application in a print variable called PrErr. The 
application interprets the error numbers and reports the error to the user. The majority of 
the errors reported are the same as the errors for the Imagewriter driver. The fax-specific 
error numbers reported to the application are not defined yet and therefore, will be reported 
by the fax driver (see Fax specific errors which follows). 


Fax-Specific Errors 


These errors, unlike the error numbers, are handled by the AppleFax modem driver. These 
types of errors are fatal and are reported to the user with an alert box, shown in Figure 11. 
Fax-specific errors fall into two types of categories: 


a Errors reported by the driver due to communication errors between the 
Macintosh and the modem. 
a Valid internal modem errors reported by the modem. 


Fax modem error: -421 (« 
Pages sent to 2652: 0 { Cancel | 


A communication error occured between 


the Macintosh and the Fax Modem. Reset 
the modem and check your serial cable. 


Figure 11: Fax Specific Error Message Alert Box 


The Macintosh-modem communication errors are displayed by using a single 
communication error message box. The actual error number is displayed with the message 
to aid in troubleshooting, as well as the number of pages transmitted to the target fax station 
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before the error occurred. Errors reported by the modem are handled in two different 
ways: 


= If the internal error is in the firmware, the message "Internal modem error” is 
displayed with the corresponding error number. 

a If the error was generated by a process beyond the control of the firmware or 
software, such as a busy signal, a descriptive message and the corresponding 
error number are displayed. 


Fax specific errors are divided into three categories: 
Macintosh-modem communication errors. 


Internal firmware errors 
Errors due to external circurnstances 


ooo 


Each of these are described in the following paragraphs. 


Macintosh-modem communication errors: These types of errors occur due to a 
communication problem between the Macintosh and the attached AppleFax modem. The 
basic error message, reported by the modem driver, is the same for all errors and was 
shown in Figure 11. The following list contains the possible error numbers displayed with 
the message: ° 


-420,FEInvid Invalid command attempted on the AppleFax modem. This 
etror could mean either that there is a bad serial connection, 
or that an application has used a low level command that 
does not exist. 


-421,FENoResp No response from the AppleFax modem. Probable causes 
for this error are that the power is off, the serial cable is not 
connected, or the modem firmware is not functioning 
properly. 

-422,FECkSum A checksum error occurred in the response data received 
from the AppleFax modem. This error may be due to a bad 
serial connection. 

-423, FEBadCrl Driver received a bad control packet from the modem. This 
error may be due to a bad serial connection. 


-424,FEBadCon Modem has informed the driver that the last packet received 
by the modem contained a bad checksum. This error may be 
due to a bad serial connection. 


-425,FEBadLen Modem attempted to send the driver too many bytes for a 
given record structure. 


-426,FEModemTO If the modem takes too long to complete an operation, it 
results in a time out error. 
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Internal firmware errors: If an error in the firmware occurs, the driver displays the 
following message: 


"An internal error has occurred in the AppleFax modem. Reset the 
_ modem and try again" 


Along with this message, an error code number will be displayed to aid in troubleshooting. 
These error code numbers are as follows: 
-410,FENolmage There is no image available to be received. 
-411,FESystem A fatal system error has occurred in the AppleFax modem. 
-412,FETooLong The packet received by the modem is too long. 
-413,FEOverFlow Some data has been lost due to buffer overflow. 


Errors due to external circumstances: This last type of fax specific errors are 
reported by the modem due to circumstances within the environment. Each error code 
number in this category has its own error message that is displayed in the alert dialog box. 
These messages and the corresponding error numbers are as follows: 


-401,FETimeOut "The AppleFax modem could not connect to the target 
device. Check your phone connections and number." 


-402,FEComm "A communication error occurred between the AppleFax 
modem and the target device. Please try again.” 
-403,FEIncompat "The target device at the current number is incompatible with 


the AppleFax modem. Check your phone number." 


-404,FEWrgVers "The firmware in the AppleFax modem is incompatible with 
this version of the AppleFax resourse." 


Status Messages 


The status message dialog box is provided to inform the user as to what the driver is doing. 
Status messages will only be displayed if the hOpt ions parameter element DIgsOn is 
TRUE. This is the default setting, however, some applications accessing the driver at a 
lower level may turn the status dialog off. 


In the currently supported status messages listed next, n is the current phone number or 
station name; p is the current page number, and FileName is the name of the saved file. 


"Spooling fax file..." 


This message is displayed as the document is being spooled 
to the disk prior to connection 


"Spooling fax file. Do not dial yet..." 
This message is displayed in place of the previous message 
if you have selected the manual dial option. 
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"Preparing fax file for transmission: page p..." ( 


The fax file is being converted into a temporary T4 encoded 
file that will be unspooled after connection. 


"Attempting to connect with n..." 


This message is displayed while connection to the receiving 
station is being attempted. 


“Connection established with n..." 
Connection to the receiving station was successful. 


"Disconnecting from n..." 


AppleFax modem is disconnecting from the receiving 
station. 


"Saving fax image as FileName...” 


This message is displayed when the Save File option has 
been chosen. 
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AppleFax Library 


Applications interfacing to the AppleFax modem can do so through one of two channels: 
either through the AppleFax library or the print manager. The library provides a 
convenient way. for certain applications to access low-level firmware commands directly 
and provides a few useful high level functions as well. 


The library was created with MPW and can be linked to any MPW application. For general 
use of the library, the following PASCAL interface files must be included in your source 
code: 


a Faxintf.p Contains the constants and structure definitions that are used in 
the library 
a FaxLibintf.p Contains the interface to the routines in the library 


When you use the AppleFax library, certain global data is automatically initiated. In order 
to initialize the global data that is used by the library, the first library call you must make is 
FxLibInit: 


PROCEDURE FxLibinit; 
The global variable FaxGlobals.iPrErr contains the error code (or zero) for any given 
library command. It is the responsibility of the application to detect and handle errors. If 


an error is detected, the application must set FaxGlobals.iPrErr to zero prior to 
executing any further library commands. 


Library Firmware Routines 


As stated, the AppleFax library is provided to allow certain applications the ability to access 
all of the low level fax firmware commands (see FxCalls.p for sample source code). In 
order to perform fax commands, the following three operations must be executed: 


g AFxCmdOpen call to allocate and initialize the overhead for subsequent calls. 
a FxCommand calls to execute any fax commands. 
a AFxCmdClose call to deallocate the overhead for the calls. 


All three of these commands use the parameter of pFCR, which is a pointer to a fax 
command record. The structure of the fax command record TFaxCmdRec is defined 


under FaxIntf.p. Following is a description of each firmware routine along with its input 
and output parameters. 


FxCmdOpen 
The fax command open (FxCmdOpen) routine uses the following format structure: 


FUCTION FxCmdOpen(pFCR: pTFaxCmdRec; DoErrDlgs, 
DoStatusDlgs: BOOLEAN): INTEGER; 


Following is the input parameter for the FxCmdOpen routine: 
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PFCR” .pPort 


DoErrDlgs 


DoStatusDlgs 


This parameter is used as a pointer to a SerialPair structure that must 
be supplied by the application. The FxCmdOpen call opens the 
serial driver to the currently established baud rate and handshaking 
for the AppleFax modem. Upon opening the serial driver, the 
inRef and outRef parameters of the SerialPair structure are set 
with the serial driver's reference numbers. If the parameter 
intInBuf is not nil, FxCmdOpen calls SerSetBuf to set an 
alternate read buffer pointed to by int InBuf with a length of 
inBufSize. If you do not want to use an alternate read buffer, 
you must set int InBuf to nil. Refer to Jnside Macintosh, volume 
2, for information on the serial driver. 


If this BOOLEAN is true, the library will display error messages 
just like the driver 


If this BOOLEAN is true, the library will display status messages 
just like the driver. 


Following are the output parameters for the FxCmdOpen routine: 


= 


FaxErr 


pFCR* .nPacket 


FxCommand 


If there is no error, this field contains zero. If the field contains 
another value, it indicates the error is either a general system error or 
a fax-specific error, as listed in FaxInt£.p. This error can also be 
checked in FaxGlobals.iPrErr. 


This parameter is used internally as a handle to memory to execute 
commands. It is automatically allocated and initialized by the 
FxCmdOpen call and the application should not modify its’ 
contents. 


The fax command routine uses the following format structure: 


FUNCTION FaxCommand(pFCR: pTFaxCmdRec): INTEGER; 


Following are the input parameters for the FxCommand routine: 


DFCR*.FaxCommand This parameter contains an integer constant that reflects the 


firmware command that is to be performed. Following is a list of 
the constants that must be used: 


FTStatus = (0; 

FTFaxDial = FTStatus +1; 
FTFaxAnswer = FTFDial +1; 
FTFaxXmit = FTFaxAnswer +1; 
FTXmitLine = FTFaxXmit +1; 
FTXmitEnd = FTXmitLine +1; 
FTFaxReve = FTXmitEnd +1; 
FTRcveBfr = FTFaxRcve +1; 
FTReveEnd = FTReveBfr +1; 
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PFCR~.hPacket 


PFCR*.pPort 


pFCR™ .pOutput 


PFCR*.pInput 


pidleProc 


FTXmitPkt = FTReveEnd +1; 


FTRcvePkt = FTXmitPkt +1; 
FTDisconnect = FTRevePkt +1; 
FTSetReg =FTDisconnect +1; 
FTGetReg = FTSetReg +1; 
FTReset = FTGetReg +1; 
FTVersion = FTCancel +1; 
FTGetResult = FTVersion +1; 
FTPickUp =FTGetResult +1; 
FTHangUp = FTPickUp +1; 


This parameter is used internally as a handle to memory to execute 
commands. It is automatically allocated and initialized by the 
FxCmdOpen call; the application should not modify its contents. 


This parameter is used as a pointer to the user-supplied SerialPair 
structure initialized by the FxCmdOpen call. 


This parameter field is used as a pointer to the structure you want to 
send to the modem with the command. These structures are 
different for each command. If there is no output structure for the 
call you are making, use nil. See "Fax Modem Command Record 
Structure" under FaxIntf.p, in Appendix B. 


This parameter field is used as a pointer to the structure that you 
want to use to receive information from the modem. These 
structures are different for each command. If there is no input 
structure for the call you are making, use NIL. See "Fax Modem 
Command Record Structure” under FaxIntf.p, in Appendix B 


This parameter field is used as a pointer to an idle procedure that is 
to be executed while the driver is performing asynchronous 
operations. You can use the library routine PrAbortCheck that 
will look for a key sequence of the Command period (.). This key 
sequence signifies that the user has terminated the operation. If 
PrAbortCheck finds this, it places the print error constant 
iPrAbort (128) into the global FaxGlobals.iPrErr. 


Following are the output parameters of the FxCommand: 


FaxErr 


pFCR*.pInput~ 
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If there is no error, this field contains zero. If this field contains 
another value, it indicates the error is either a general system error or 
a fax specific error, as listed in FaxIntf.p. This error can also be 
checked in FaxGlobals.iPrErr. 


If the fax command that you are executing returns data, the data is 
put into the Input structure that pInput points to. 
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FxCmdClose 


The fax command close (FxCmdClose) routine uses the following format structure. Note 
that there are no output parameters for this routine. 


PROCEDURE FxCmdClose(pFCR: pTFaxCmdRec) ; 


Following is the input parameter for the FxCmdClose routine: 


PFCR This parameter field is used to de-allocate the overhead for the calls. 


High-Level Firmware Routines 
The high-level firmware routines consist of FxDumpFile and FxConvertFile. 


FxDumpFile 

Fax dump file (FxDumpFile) is a high-level library routine that uses a combination of 
lower-level fax firmware calls and driver-imaging techniques to allow an application to 
transmit already saved fax files to a fax machine. FxDumpFile is used independently of fax 
firmware calls, which means that FxCmdOpen is not necessary for this routine to function 
properly. FxDumpFile automatically handles the dialing of the phone, the connection, 
group 2 and group 3 encoding, and imaging. The format for this routine is as follows: 


FUCTION FxDump(hPrint: THPrint; hOptions: THOpts; 
DoErrDlgs, DoStatusDlgs: BOOLEAN): INTEGER; 


where hPrint is a handle to a print record (structure THPrint) and hOptions isa 
handle is a handle to a user allocated fax options record (structure THOpts in 
FaxCInt f.p) to be used in the dumping process. 


Following are the input parameters for the FxDumpFile routine: 


hPrint This parameter is used as a handle to a print record. If you specify 
nil for this parameter, FxDumpF ile will automatically allocate, 
initiate, use, and deallocate its own print record. However, if you 
want to use your own print record, you must call the library routine 
FlPrintDefault in order to set up the print record prior to 
calling FxDumpF ile. 


hOptions This parameter is used as a handle to user allocated fax options 
record (see Appendix B, structure THOpt s under FaxIntf.p) 
that is to be used in the dumping process. Included in resource file 
FxLib-rsre is a resource containing the HOptions. This resource 
type is 'FOPT’ with a resource ID of -8191. The following list 
contains the option fields in the hOptions record: 
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Retries. This field contains an integer that specifies the number of 
times the library attempts to retry transmission before reporting 
errors. 

ManualDial. This is a boolean for manual-dialing mode. Manual 
dialing is currently not available through the library, therefore this 
option is ignored. 

ModeFlg: .This field contains a 1-byte string that is used to specify 
the dialing mode of tone or pulse using the characters t/ T and p/P, 
respectively. 

DialNumStr. This field contains the string used to specify the 
telephone number of the target station. 

IDNum. This field contains the identification information that is 
used during the handshaking process with a fax machine. The 
contents of this field must be no more than 20 characters and contain 
only ASCII numbers or spaces. This field usually contains the 
phone number of the telephone attached to the AppleFax modem. 
StationID. This field contains a message that is to be imaged at the 
top of the each transmitted page. 

DoSID. Set to TRUE, this boolean indicates that the StationID is to 
be imaged. . 

StationName: This string contains the name of the target fax station 
and is displayed in the status window. 

SaveFileRec. This record is used internally to save fax files. 


AddrBookRec: This record is used internally to keep track of the 
location of the most resently used fax address book. 

pFileChain: This record points to the first element in a queue of file 
description records of the files to be transmitted. Following are the 
elements of this record: 


cFLink Pointer to the next TFxFileChain file record. If it 
is the last record, this element is NIL. 

cFName File name string. 

cVRefNum Volume reference number of the file. 

cDirID ID of the directory to find the file. 


DoErrDigs: If the BOOLEAN is true, this library displays the error 
messages just like the driver. 

DoStatusDigs: If this BOOLEAN is true, the library displays the 
status messages just like the driver. 


Following is the output parameter for the FxDumpFile routine: 


FaxErr 
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If there is no error, this field contains zero. If the field contains 
another value, it indicates the error is either a general system error 
(as defined in Inside Macintosh) or a fax-specific error, as listed in 
FaxIntf.p. This error can also be checked in 
FaxGlobals.iPrErr. 
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FxConvertFile 


The fax convert file (FxConvertFile) library command is used to allow the application to 
convert a group 3 / T4 or group 2 encoded file to the standard fax file format. This call 
assumes that the application has used low-level fax firmware commands to receive raw 
encoded data from a fax machine and then stored the data with the file format. This call can 
be made as shown below: 


FUNCTION FxConvertFile(pInFile,pOutFile: pTFxSaveFile): 
Where both the pInFile and pOutFile are pointers to TFxSaveFile records that 


specify the input and output files. It is not necessary for the output file to exist prior to 
calling this routine since FxConvertFile creates the output file automatically. 


General Routines 
This routine is used to default a user's print record: 


PROCEDURE FlPrintDefault (hPrint: THPrint): 


The General routine can be specified as an idleProc that looks for the Command, Shift, and 
Period keys to be pressed: 


PROCEDURE PrAbortCheck 


File Structures 


The following description of the AppleFax file structure assumes that you have a good 
understanding of the Print Manager and QuickDraw (see Inside Macintosh, volumes 1 and 
2). 


Fax File Format 


The AppleFax modem transmits and receives fax files. Fax files are created by the driver 
and contain header and page break information followed by a series of pages in Pict format 
(refer to Macintosh File Format and Picture Structure Graphic Applications, published by 
Apple Computer July 15, 1987). The format of the header in a fax file is a TPfHeader 
structure defined in the PASCAL include file MacPrint.p. The header contains a print 
record (TPrint) followed by the page directory structure TPfPgDir. The page directory 
consists of an integer, specifing the number of pages in the file, and an array of longints 
that specify the offest from the begining of the file to the start of each page. Figure 12 
shows the format of the fax file header. 


TPrint Integer Picture Offset 
2 Bytes 128 4-byte fleids 
Figure 12: Fax File Header Format 
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Each page contains a rectangle, RPage, that specifies the drawing area of the pict for that 
page. The 10 bytes following the page rectangle are fake overhead bytes used for the 
PicHandle. The variable field following these 10 bytes are the bytes of the picture itself. 
Figure 13 shows the format of the picture. Since fax files are basically pictures files, you 
can call DrawPicture to image the pages on the screen or dump them to printer grafports. 


RDirty Overhead Picture 
16 Bytes 10 Bytes n Bytes 
Figure 13: Fax File Picture Format 


Drawing a Fax File Picture 


The rectangle RPage in the PrinfoPt record of the TPrint record in the header of the fax file 
specifies the rectangle that is used in your call to DrawPicture. Note that the rectangle size 
is intended for imaging faxes at 216 dots per inch. Therefore, if you want to display a fax 
file on the screen at 72 dpi, you must divide the rectangle by 3 before calling DrawPicture. 
In order to draw a picture from an existing fax file, you must use the page directory to 
locate the beginning of the page. The rectangle at the beginning of each page description 
specifies the minimum imaged area within RPage. For example, if the page has a drawing 
only in the upper portion of the page, the RDirty rectangle is used for internal optimizations 
and you can ignore it. Prior to calling DrawPicture, you must do the following 
manipulation involving a QuickDraw bottleneck: 


1) Create a Pichandle that is 10 bytes long 
2) Read the 10 bytes following the RDirty rectangle into this handle. 


The data in this handle is required as Picture overhead for DrawPicture. The actual data for 
the picture is supplied by switching the quickdraw bottleneck 'GetPicProc’ to point to your 
procedure that reads the picture data from the file upon demand from quickdraw. 
Temporary T4 File 

Each file that is to be transmitted to a fax station has a temporary file created using the T4 


file format. This format is defined for the sake of completness since no user accessable 
routines are contained in the library to handle this file format. 
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The temporary file is stored as a series of lines represented as word data lengths followed 
by T4 data: 


<word> length of line, <block> T4 line data 


<word> length of line, <block> T4 line data 
<word> Page break (iSNewPage) or last page (iSLastPage) 


Constants are used to indicate page breaks and last page. Note that there are no page break 
constants at the beginning of the file. 


Received File 


To convert received fax data into the previously described fax file format, you can use the 
library command FxConvertFile. To do this, you must first organize your fax encoded 
data into a packet format. These packets consist of an integer that specifies data type, an 
interger indicating the length of the data, and the data itself. The constants for the data 
types are defined in Faxintrf.p. - 


. 


The header information expected at the beginning of each file is as follows: 


Type Length Data 


REFCapabilities sizeof(SFIRec) Capabilities record SFIRec 
received using the FaxAnswer 
command. 

REFSIDStr sizeof(SIDStr) Station ID string received 
using the FaxAnswer 
command. 


The following information is required to describe each page: 


Type Length Data 

REFPageS tart len of data received Data received using 
ReceiveBuffer command. 

REFPageData len of data received Data received using the 
ReceivBuffer command. 
Repeat until entire page is 
received. 


To specify the end of the last page of fax transmission, use the following information: 


Type Length Data 
REFLastPage 0 none 
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Appendix A 


-- Capabilities and Result Formats 
(For FaxDial and FaxAnswer Commands) 


This appendix describes the format of the Capabilities and ResultCap fields used in the 
FaxDial and FaxAnswer commands. Both of these are variable length fields containing 
a string of data preceded by a length byte. The maximum length of these fields must not 
exceed CapSize (8 bytes). 


The following table gives the contents of the first four bytes (bytes 0, 1, 2, and 3) 


following the length byte. Bytes after byte 3 are not yet defined by the T.30 standard. 
Following the table is a description of the bits and their values in more detail. 
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A-2 


Ne Pee 


Ww 


Capabilities (7.30 DIS 


Group 1 Capabilities 
Group 2 Transmitter 
Group 2 Receiver 
Reserved Group 2 bits 


Group 3 Transmitter 
Group 3 Receiver 


Dara signalling rate 


V.27 ter fallback mode 

V.29 

V.27 ter 

V.27 ter and V.29 

Reserved for future group 
7.7 lines/mm. (200 lpi) 
2-dim. coding capability 
Recording width capabilities 


1728 pixels 

1728 or 2048 pixels 

1728, 2048, or 2432 pixels 
Invalid 


Recording length capability 


A4 (297 mm.) 

A4 (297 mm.) and B4 (364 mm.) 
Unlimited length 

Invalid 


Scan line time capability 


20ms @ 100 lpi/20ms @ 200 Ipi 
S5ms @ 100 lpi/Sms @ 200 lpi 
10ms @ 100 lpi/10ms @ 200 lpi 
20ms @ 100 lpi/10ms @ 200 lpi 
40ms @ 100 Ipi/40ms @ 200 lpi 
40ms @ 100 lpi/20ms @ 200 Ipi 
10ms @ 100 Ipi/Sms @ 200 Ipi 
Oms @ 100 lpi/Oms @ 200 lpi 
Extend field 


Unsupported by the Fax Modem 
Extend field 
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ResultCap (7.30 DCs) 
Group | Capabilities 


Receive Group 2 
Reserved Group 2 bits 


Receive Group 3 
Data Signalling Rate 


2400 bps V.27 ter 

9600 bps V.29 

4800 bps V.27 ter 

7200 bps V.29 

Reserved for future group 
7.7 lines/mm. (200 Ipi) 
2-dimensional coding 
Recording width 


Maximum recording length 


A4 (297 mm.) 

B4 (364 mm.) 
Unlimited length 
Invalid 

Maximum scan line time 


Extend field 


Unsupported by the Fax Modem 
Extend field 
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Byte 0, Bits 0-2: Group 1 Capabilities 


Group 1 is not supported by the AppleFax modem. These bits should be set to 0 in the 
Capabilities field and ignored in the ResultCap field. 


Byte 0, Bit 3: Group 2 Transmitter 
Byte 0, Bit 4: Group 2 Receiver 
Byte 1, Bit 0: Group 3 Transmitter 
Byte 1, Bit 1: Group 3 Receiver 


In the Capabilities field, these bits enable the controller to specify its capabilities to the - 
remote device. The controller sets the bits according to its capabilitites. 


In the ResultCap field, these bits are used to tell the controller which operations have been 
selected from the point of view of the remote device. The following table lists how the 
selected operations will be indicated: 


Operation bt Bit Set 

Group 3 transmission from controller to Group 3 Receiver; byte, bit 1 
remote device 

Group 3 reception from remote device Group 3 Transmitter, byte1, bit 0 
to controller 

Group 2 transmission form controller to Group 2 Receiver, byte 0, bit 4 
remote device 

Group 2 reception from remote device Group 2 Transmitter, byte, bit 3 
to controller 


If both group 2 and group 3 capabilities are available, group 3 operations will have priority 
and be selected over group 2 operations. 


Byte 1, Bits 2,3: Transmission Speed Capabilities 


The AppleFax modem is capable of transferring data over the phone lines at four different 
data rates: 9600, 7200, 4800, and 2400 bps. Other fax modems have some subset of 
these data rates available. In certain rare situations, it may be desirable to make the fax 
modem restrict its operation to a subset of its available data rates. Bits 2 and 3 of byte 1 in 
the Capabilities field allow this type of restriction to be controlled. The possible data rate 
restriction settings are as follows: 


Bits 3.2 ‘Restrict 


0,0 2400 bps 

0,1 9600 or 7200 bps 

1,0 4800 or 2400 bps 

1,1 9600, 7200, 4800, or 2400 bps 


The last subset allows full functionality. 
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In the ResultCap field, the fax modem returns the data rate that will acthally be used for the 
data transfer. The bit values for each data rate are given below: 


0,0 2400 bps 
0,1 9600 bps 
1,0 4800 bps 
1,1 7200 bps 


No matter what data rate the modem uses over the phone line, data will always be 
transferred between the controller and the modem at the currently selected baud rate 
(typically 19,200 baud). 


Byte 1, Bit 6: Vertical Resolution 
In the Capabilities field, this bit specifies 200 lpi capability. 


In the ResulrCap field, this bit specifies whether 200 lpi resolution (value of" 1') or 100 
Ipi resolution (value of '0’) will be used for the transmission. 


Byte 1, Bit 7: Two-Dimensional Coding 


In the Capabilities field, this bit specifies that the controller has two-dimensional coding 
capability. 


In the ResultCap field, this bit specifies whether two-dimensional (value of '1’) or one- 
dimensional (value of '0’) coding will be used for the transmission. 


Byte 2, Bits 0,1: Recording Width 
In the Capabilities field, these bits specify the controller's image width: 


Bits1.0 Image Width 
0,0 1728 pixels 
0,1 2048 pixels 
1,0 2432 pixels 
Ti Invalid 


In the ResultCap field these bits specify which width is to be used for the transmission: 


Bits 1,0 Image Width 

0,0 1728 pixels 

0,1 1728 or 2048 pixels 

1,0 1728, 2048, or 2432 pixels 
1,1 Invalid 
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Byte 2, Bits 2,3: Recording Length 
In the Capabilities field these bits specify the controller's image length: 
Bits 1.0 Image Length 
0,0 A4 (297 mm) 
0,1 A4 (297 mm) and B4 (364 mm) 
1,0 Unlimited length 
1,1 Invalid 
In the ResultCap field these bits specify which length will be used for the transmission: 


Bits1.0 Image Length 


0,0 A4 (297 mm) 
0,1 B4 (364 mm) 
1,0 Unlimited length 
1,1 Invalid : 


Byte 2, Bits 4-6: Minimum Scan Line Time 


In the Capabilities field, these bits specify the minimum time the controller needs to 
process each line of a received graphic image: 


Bits 6.5.4 Mini Line Time for Receivi 
0,0,0 20 ms for 100 Ipi, 20 ms for 200 Ipi 
0,0,1 5 ms for 100 Ipi, 5 ms for 200 Ipi 
0,1,0 10 ms for 100 Ipi, 10 ms for 200 lpi 
0,1,1 20 ms for 100 Ipi, 10 ms for 200 Ipi 
1,0,0 40 ms for 100 Ipi, 40 ms for 200 Ipi 
1,0,1 40 ms for 100 Ipi, 20 ms for 200 Ipi 
1,1,0 10 ms for 100 !pi, 5 ms for 200 Ipi 
i 0 ms 


Some of these settings allow lines to be sent twice as fast when 200 Ipi vertical resolution 
is being used. 


In the ResultCap field, these bits specify how much time is to be allocated for sending 
each line: 


Bits 6.5.4 Minimum Time per Line 


0,0,0 20 ms 
0,0,1 5 ms 
0,1,0 10 ms 
1,0,0 40 ms 
1,1,1 0 ms 
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Byte 2, Bit 7: Extend 


This bit must be set to extend the record's length to four bytes. 


Byte 3, Bits 0-6: Ignored 
These bits are ignored by the fax modem in the Capabilities field. 
In the ResultCap field, these bits are passed directly from the remote device. 


Byte 3, Bit 7: Extend . 
This bit must be set to extend the record's length to five bytes. 


Examples 
Following are some examples of the previously described bit settings. 
Example 1 


This example allows 200 line per inch group 2 or 3 reception or transmission at any 
available baud rate. 


Byte 0: 

Group 2 transmission | $08 
+ Group 2 reception; $10 
= Byte 0 $18 
Byte 1: 

Group 3 transmission $01 
+ Group 3 reception $02 
+ V.27 and V.29 capability $0C (9600, 7200, 4800, or 2400 available) 
+ 200 Ipi $40 
+ One dimensional coding $00 
= Byte 1 $4F 
Byte 


2: 
1728 pixel recording width $00 


+ Unlimited recording length $08 
+ 0 ms minimum line time $70 
= Byte 2 $78 
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The capabilities string (including the length byte) should be set to: $03, $18, S4F, $78 


Example 2 


This example allows 100 line per inch group 2 or 3 reception or transmission at any 
available baud rate. 


Byte 0: 

Group 2 transmission $08 
+ Group 2 reception $10 
= Byte 0 $18 
Byte 1: 

Group 3 transmission $01 
+ Group 3 reception $02 
+ V.27 and V.29 capability $0C (9600, 7200, 4800, or 2400 available) 
+ 100 Ipi $00 
+ One dimensional coding $00 
= Byte 1 SOF 
Byte 2: : 

1728 pixel recording width $00 
+ Unlimited recording length $08 
+ 0 ms minimum line time $70 


Byte 2 $78 
The capabilities string (including the length byte) should be set to: $03, $18, SOF, $78 


Example 3 


This example allows 200 line per inch group 3 reception or transmission at a restricted 
baud rate of 4800 or 2400 bps. 


Byte 0: 
No BP 2 is aa 
= Byte 0 


Group 3 transmission 
+ Group 3 reception 
+ V27 capability (4800 or 2400 available) 
+ 200 Ipi 

+ One aineamicnal coding 


Byte 1 


£8esss 88 


2 
1728 pixel recording width $00 


+ Unlimited recording length $08 
+ 0 ms minimum line time $70 
= Byte 2 $78 


The capabilities string (including the length byte) should be set to: $03, $00, $4B, $78 
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Appendix B 


AppleFax Library Interface Code 
(File FaxIntf.p) 


Appendix B provides you with a hard copy of the AppleFax library interface code file 
FaxIntf.p. 
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File: Faxintf.p ( 
Fax Modem driver includes 


Appendix A of the Fax Modem Driver Specification 


Copyright (C) 2986, 1987 
Apple Computer Inc. 
ALL RIGHTS RESERVED 


rst Writing: 
O7-NOV-86: P. Allen Cronce 


Modification history: 
PAC / 11-MAY-87: Updated for new firmware specs 
PAC / 15-AUG-87: new firmware commands 
PAC / 22-SEP-87: Modified THOpts to handle file list 


INTERFACE 
{ ween ween nene Sr rT wwe we mmm wen een mmm, ae oe am Som eserewe w=) 
USES 
{SLOAD MacIntf.LOAD} os F 
MemTypes, QuickDraw, OSIntf, Toolintf, PackIntf; x 
{$LOAD } 
{totter ttn nnn en nn nnn nnn nn nn ener nn nnn nnn nnn enon nen ene} 
CONST 
{ current version of the firmware that will work with this driver} 
iCurFirmLevel = 20; . ( 
{time constants} 
OneSec = 60; { number of ticks in one second } 
OneMin = OneSec * 60; { number of ticks in one minute } 


{ Fax timeout tickcount constants } 


FATTimeOut = OneSec * §; { 5 second attention time out } 
iFaxDiaiTo = OneMin * 2; { FaxDial time out } 
iFaxXmitTO = OneMin * 1; { FaxTransmit time out } 
iBleedDtaTO = OneSec * 45; { firmware data bleed timeout } 
iXmitEndToO = OneSec * 20; { TransmitEnd time out} 

{ 


LDisconneceTo = OneSec * 20; ‘Disconnect time out} 


iFaxAnswerTO = OneMin; {1 minute - FaxAnswer} 
LFaxRecvToO = OneMin;: {1 minute - FaxReceive} 
iRecvEndTO = OneMin * 2; (4 minute - ReceiveEnd} 
iXmitPkeTo = OneMin; {1 minute - TransmitPacket} 
LRecvPktTO = OneMin; {1 minute - ReceivePacket} 
iGetRegTO = OneSec * 5; {5 seconds - get reg} 
iSetRegTO = OneSec * 5; {5 seconds - set reg} 


{ Horizontal resolution } 
FPixleWidth = 1728; 
FByteWidth = 216; {FPixleWidth DIV 8} 


{ Group 2 capabilities } 
{ In SFIRec.data[(0] } 


G2_Transmit = 8; { Can transmit group 2 } 

G2_Receive = 16; { Can receive group 2 } 

G2_10C176 == 32; { IOC = 176 rather than 264 } ( 
G2_ReceiveTst = {for bit tst) f 


4; 
G2_TransmitTst = 3; {for bic tst} 


{ Default croup 2 capabilities: } 
G2 Default = (G2_Transmit+G2_Receive); 
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{ Group 3 capabilities } 

{ In SFIRec.data[1l] } 
G3_Transmit = 1; { 
Gi_Receive = 2; { 


G3_V27slow = 0; { 
G3_V27 = 8; { 
G3_v29 = 43. — { 
G3_V27_V29 = 12; { 
G3_2400 = 0; { 
G3_4800 = 8; { 
G3_7200 = 12; { 
G3_9600 = 4; { 
G3_200lpi = $40; { 
G3_100lpi = $BF; { 
G3_200lpiTst = 6; { 
G3_2dim = $80; { 


( In SFIRec.data(2] } 
G3_W1728 = $00; { 
G3_W2048 = $01; { 
G3_W2432 = $02; 


G3_LA4 = $00; { 
G3_LAny = $08; { 
G3_LB4 = $04; { 
G3_0ms = $70; { 
G3_5ms = $10; 
G3_10ms = $20; 
G3_20ms = $00; 
G3_40ms = $40; 
G3_10msHalf = $60; { 
G3_20msHalf = $30; { 
G3_40msHalf = $50; { 


G3_Extend = $80; { 


{ Default group 3 capabilities: } 
G3_Default = (G3_Transmit+G3 


{ Mode specifiers: } 
{ Act like a standard Fax machine 
Standard = 0; 
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Can transmit group 3 } 
Can receive group 3 } 


Can only use v.27 2400 bps } 


Can use 
Can use 
Can use 


Using V. 
Using Vv. 
Using V. 
Using V. 


200 lpi 


and this with capabilities to clear 200 lpi } 


bit posi 


V.27 2400 or 4800 bps } 
V.29 7200 or 9600 bps } 
V.27 or V.29 } 


27 2400 bps } 
27 4800 bps } 
29 7200 bps } 
29 9600 bps } 


rather than 100 } 


tion number for btst } 


Two dimensional encoding } 


Maximum 
Maximum 
Maximum 


Maximum 
Maximum 
Maximum 


Minimum 


Minimum 


width of 1728 pixels } 
width of 2048 pixels } 
width of 2432 pixels } 


length: A4 size } 
length unlimited } 
length: B4 } 


scan line times in milliseconds } 


line times. In high } 


resolution mode, time can be } 
decreased by half. } 


extend field. } 


Receive+G3_V27_V29+G3_W1728+G3_LA4+G3_Oms) ; 


-} 


{ Act like a standard Fax but identify as an AppleFax. } 


Limited = 1; 


{ Use AppleFax mode if both sides are AppleFaxs. } 


AppleFax = 2; 


{ Fax command / response types } 


FTStatus = 0; 
PTFaxDial = FTStatus 
FTFaxAnswer = FTFaxDial 
FTFaxXmit = FTFaxAnswer 
FTXmitLine = FTFaxXmit 
FTXmitEnd = PTXmitLine 
FTFaxReve = FTXmitEnd 
FTReveBfr = PTFaxReve 
FTReveEnd = FTReveBfr 


FTXmitPke = FTReveEnd 


Se i ec ee oe a 


Page 


9/23/87 3:12 PM 


FTRevePke 


FTDisconnect 


FTSetReg 
FTGetReg 
FTReset 
FTCancel 
FTVersion 


FTGetResuls 


FTPickUp 
FTHangUp 


my oF id 
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= FTXmitPkte + 13 
= FTRevePkt + 13 
= FTDisconnect + 1; 
= FTSetReg + Ls 
= FTGetReg 5 ae 
= FTReset +1; 
= FTCancel +13 
= F¥Version + 13 
= FTGetResult +1; 
= FTPickUp + 1; 


-400; 


° 
e 
e 


Wm oO 


{base error added to other errors for uniqueness} 
{no error} 


{Firmware reported errs due to external circumstances} 


FETimeOut = <1; 
FECommErr = <2; 
FEIncompat = -3; 
FEWrgVers = -4; 


{Time out error} 

{Communication error with the target device} 
{target device is incompatible} 

{wrong version of the firmware for the software} 


(Firmware reported internal system errors} 


FENoImage = -10; {no image is available to be received} 

FESystemErr =z -ll; (fatal internal system error} 

FEToaoLong = -12; {modem received a packet that was too long) 

FEOverF low = -13; (buffers were not read by the driver fast enough} 
{Firmware reported errs due to modem / driver problems } i 

FEInvld = -20; {Invalid command and cannot be executed} 
{software driver reported errors when the modem is flaked} 

FENoResponce = -21; {No responce from the fax modem} 

FECKSumErr mw -22; {chksum error in the responce data received) 

FEBadCtrl = -23; {bad contrel packet returned} 

FEBadComfirm ww 24; {bad comfermation of sent packet} 

FEBadLength = -25; {modem tried to send too many bytes} 

FEModemTO = -26; {modem is taking too long} 


~ 


FeDufusErr 


-29; 


This error happens if the dialogs are turned off and manual dial is used } 


{ the user is a dufus } 


{software driver reported errors when performing T4 data conversion} 


FET4IinEmpty 
PET4OutFull 
FET4DataErr 


{ Error cede ranges 


{ All errors } 


PEeFrircst 
FELast 


“31; 
-32; 
-33; 


} 


{empty input buffer) 
{output buffer full} 
{data syne error} 


FETimeOut; 
FEDufusErr; 


{ problems between modem and me } 
= FEInvld; 
= FEModemTO; 


FENoComFirst 
FENoComLast 


{ firmware reported errors due to external circumstances } 
= FETimeOut; 
= FEWrgqVers; 


FEXFirmFirst 
PEXFirmLasct 


{ firmware reported errors due to internal problems } 
= FENoImage; 
= FEOverf low; 


FEIFirmFirst 
FEIFirmLast 


{ generic cancel alert } 


iCancelAx 


= -8183; 


{ PAC / General purpose cancel alert } 


{Error message string res numbers} 


iInternErrStr 


= -8179; 


{generic intenal error} 
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iMMComErrStr = ~-8180; {generic Mac / modem communication error} 


iATMsgBaseStr = -8180; (base messages for external error reporting} 


iTimeOutStr = LATMsgBaseStr + FETimeOut; {Time out error} 
icomErrStr = LATMsgBaseStr + FECommErr; {Com error with target} 
ilIncompatStr = iATMsgBaseStr + FeEIncompat; {target is incompatible} 


{status dialog} — 
iPrStatDlg = ~8190; 


{STR# constants for status messages} 


iStatStrResID = -8190; {resource ID of our STR#} 
IStatItem = 1; 

(indices into the strings within this res} 

isPrep = 1; 

isMDPrep = isPrep +45 

isAtmptCon = isMDPrep + 1; 

isConnected = isAtmptCon + 1; 

isXmitPage = isConnected + 1; 

isDiscon = isXmitPage + 1; 

isSaving = isDiscon +13 

isManual = isSaving +l; 

isTo = isManuai ele 

isPage = isTo 16 

isDots = isPage + 1; 

isMPCancel = isDots + 1: 

isPagesSent = isMPCancel + 1; + 

isError = isPagesSent + 1; < 

isSpooiT4 = isError + 13 = 

isFaxNum = isSpoolT4 + 1; 

isRetry = isFaxNum + 1; 

isIniting = isRetry + 1; 


{ resource type of the fax options } 
FxOptsType = 'EFOPT'; 


{ Fax file type and creator } 


LF xType = $46465846; {"FEXE"} 
(1LFxSig = $46535953;} ("FSYS"} 
lFxsig = $46414658; {"FAFX™} 
{length constants for Fax firmware commands} 
iCapSize = 8; 
iIDNumSize = 22; 
iAFISize = 64; 
iPNumSize = 64; 
iTIDSize = 26; {Terminal identification string} 


(Extended status} 
ixSXmitDone = $01; (Modem has finished transmitting} 


(File buffer size for PicFile State Object} 
LFxIOBlLkBytes =~ 512; 
{Library constants} 


{raw encoded file packet types} 


REFCapabilities = Q; {capabilities} 
REFSIDStr = 1; (Station id string} 
REFPageStart = 2; {start of the page} 
REFPageData = 3; {the page} 
REFLastPage = 4; {terminator} 

iStationName = 20; 

iPhoneNumber = 20; 

iPassword = 20; 


iFileName = 64; 
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ivVolName = 
iMachType = 
Via = 
iTimeStr = 
TYPE 

TStationNamestr 


TPasswordStr 
TFileNameStr 
TVolNameStr 


{w---- Internal 
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= STRING [iStationName]; 
= STRING[iPassword]; 
= STRING(iFileName]; 
= STRING[iVolNamej; 


a 
Ls) 


we 
=? 


e 
= SIGNEDBYTE; 


fax packet protocol structures -----~----~------~--- 212. } 


{Fax packet header} 
FPHeader = PACKED RECORD 


CmdType, 
Hilen, 
LoLen, 


CkSuml: uchar; 


END; 


(Pointer list record) 


PtrrListRec = PACKED RECORD 
Length: INTEGER; 
thePtr: bufPtr; 

END; 


pPtrListRec = “PtrListRec; 
hPtrListRec = “pPtrListRec; 


{This structure simplifies use of the serial ports by grouping the 
input and output ports and buffer pointers. } 
SerialPair = PACKED RECORD 


inRef: INTEGER; {serial input reference number} 
outRef: INTEGER; {serial output reference number} 
inBufSize: INTEGER; {size of the alternate input buffer (optional) } 
intInBuf: BufPtr; {pointer to ser input buffer, if any} 
END; 


pSerialPair = “*SerialPair; 


{ Fax packet protocol record } 


FaxPacket = PACKED RECORD 
Header: FPHeader; 
NumOutPtrs: INTEGER; { Number of pointers in the pointer list } 
hOucPtrs: hPtrListRec; { Hdl to list of ptrs that define the dta bfr } 
NumInPtrs:; INTEGER; { Number of pointers in the pointer list } 
hinPtrs: hPtrListRec; { Hdl te list of ptrs that define the dta bfr } 
CkSum2: INTEGER; { checksum of data } 
LastCmd: INTEGER; { last executed command } 

END; 


PFaxPacket = “FaxPacket; 
hFaxPacket = “pFaxPacket; 


{ record to store the memory management states of a packet protocol record } 
FStateRec = PACKED RECORD 


Packet, { packet mem state } 
OutPtrLst, { output pointer list state } 
TaPtrLst, { input pointer list state } 
Fill: uchar; 
END; 
{~---~ General Fax command structures ------------------ bashes } 


{Strings} 
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TDNumStr = STRING(iIDNumSize - 1]; 
prIDNumStr = *IDNumSctr; 

TIDStr = STRING[(iTIDSize - 1]; 
pTiIpDStr = “TIDStr; 


PNumStr = STRING(iPNumSize - 1]; 


{Standard Fax Info: contains information about the capabilities of standard 
group 2 and group 3 fax machines. It is a variable length string preceded by 
a length byte, but in normal applications only 3 bytes are required. 

Advanced applications may wish to use more bytes.} 

SFrIRec = ARRAY (0..iCapSize-1] OF uchar; { the bytes } 

pSFiIRec = “SFIRec; 


{Apple Fax Info: contains extended AppleFax information which is used 
only when two AppleFax devices are communicating with eacn other.} 


AFIRec = ARRAY [0..iAFISize-1] OF uchar; { the bytes } 


{Record for xmit/receive line/packet command} 


FLineRec = RECORD 
Length: INTEGER; { number of bytes in the line } 
Data: BufPtr; { the bytes } 
END; 


pFLineRec = *FLineRec; 


{Standard Result Data} 
TFGenResult = PACKED RECORD 


Result: SIGNEDBYTE; (result of call}: 
END; 
{----- Fax modem command record structures ---------sene n-ne nen -~---} 


{The following structures are used with the firmware command calls to 
the fax modem} 


{== Status Se EN ES TACs eT Sees ess } 
{Command Data} 
{NIL} 


{Return Data} 
TFIStatus = RECORD 


Result: SIGNEDBYTE; {status info} 
Command: SIGNEDBYTE; {currently executing command} 
ExtStatus: SIGNEDBYTE; {extended status} 

END; 


pTFIStatus = “TFIStatus; 


(Result Data} 
{NIL} 


(== PaxDial =22ss2eseeneneee eee ee2 eek es SEs 2222S 22228 SST 2s Se sess } 
{Command Data} 
TFOFaxDial = PACKED RECORD 


PhoneNum: PNumStr; {phone number to diai} 

IDNum: IDNumStr; {station ID string} 

Capabilities: SFIRec; {capabilities} 

Mode: SIGNEDBYTE; {type of connection required} 

fill: SIGNEDBYTE; {filler} 

AppleFaxiInfo: AFIRec; {apple fax specified information} 
END; 


pTFOFaxDial = “TFOFaxDial; 


(Return Data} 
(NIL} 


{Result Data) 
TFRFaxDial = PACKED RECORD 
Result: SIGNEDBYTE; {result of cail} 
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fillo: SIGNEDBYTE; {filler} 

IDNum: TDNumStr;: {station ID string} 

ResultCap; SFIRec: {result capabilities} 

Mode: SIGNEDBYTE;: {type of connection required} 

filll: SIGNEDBYTE; {more filler} 

AppleFaxInfo: AFIRec: {apple fax specified informaticn} 
END; 
PIFRFaxDial = “TFRFaxDial; 


(== FaxAnswer SES SSSALS AST TS AAT teehee ses eeaee ee een eeasenesenne } 


{Command Data) 
TFOPaxAnswer 
TONum: 


Capabilities: 


Mode: 
f4ll: 


AppleFaxInfo: 


END; 
pTFOFaxAnswer 


{Return Data} 
{NIL} 


{Result Data} 
TFRFaxAnswer 
pTFRF axAnswer 


{== FaxTransmit 
{Command Data} 
{NIL} 


{Return Data} 
{NIL} 


{Result Data} 
TFRFaxXmit = 
pTFRFaxXmit = 


PACKED RECORD 

TONumStr;: {station ID string} 

SPIRec; {capabilities} 

SIGNEDBYTE; {type of connection required} 
SIGNEDBYTE: {filler} 


AF IRec; {apple fax specified information} 
ATFOFaxAnswer; 

TERFaxDial; {same as FaxDial} 

“TERE axAnswer; 


a 


nterhet bate ttt ttt tt TT Ty SROSCS See SBS SSUES SAE } 


TFGenResult; {result of call} 
“TFREaxXmit; 


{== Transmit Line SENS SASS SSAA SSS eae See secen AS } 


{Command Data} 
TFOXmitLine = 
pTFOXmitLine 


{Return Data} 
{NIL} 


{Result Data} 
TFRXmitLine «= 
pTtFRXmitLine 


{== TransmitEnd 
{Command Data} 
TFOXmitEnd = 
LastPage: 
END; 
pTFPOXmitEnd = 


{Return Data} 
{NIL} 


{Result Data} 
TFRXmitEnd «= 
Resule: 
Quality: 
END; 
pTFRXmitEnd = 


= 
J 
= 


L 


ineRec; 
“TFOXmitLine; 


TFGenResult; {result of call} 


“TFRXmitLine; 


20 SES Se Seo See SSE ese Sees ween eee } 


PACKED RECORD 


BOOLEAN; {TRUE is last page} 


“TFOXmitEnd; 


PACKED RECORD 


SIGNEDBYTE; {result of the cail} 
SIGNEDBYTE; {0 if image was unacceptable} 


“TFRXmitEnd;: 
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(== FaxReceive =s=sseesantes2ssess ase eS SS CSRS SS SS Sse SSS SSS ESSE SS TSSSSSSS } 


{Command Data} 
{NIL} 


{Return Data} 
{NIL} 


‘Result Data} 
TFREaxReve = TFGenResult; {result of call} 
PTFRFaxReve = “TFRFaxRcve; 


(== ReceiveBuffer ==s=sacssnssss2s2sesesusseaneassasssssssaeessesessas2s } 
{Command Data} 
TFORcveBfr = PACKED RECORD 
BufSize: INTEGER; {number of bytes to receive} 
END; 
pTFORcveBfr = *TFORcveBfr; 


(Return Data} 
TFIRcveBfr = PACKED RECORD 


Result: SIGNEDBYTE; {result of the call} 

Done: SIGNEDBYTE; {1 if last data of the current image} 

Length: INTEGER; {length of the buffer} 

Data: BufPtr; (pointer to buffer to receive data} 
END; < 


. 


pTFIRcveBfr = “TFIRcveBfr; 


(Result Data} 
TFRReveBfr = PACKED RECORD 


Result: SIGNEDBYTE; {result of the call} 
Done: SIGNEDBYTE; {1 if last data of the current image} 
END; 


pTFRReveBfr = “TFRReveBfr; 


{= Rece iveEnd =ss2ss2sses22252sSes enna eee SeERT Tas SSS 2 TTI assess Ss Ee } 
{Command Data} 
TFORcveEnd = PACKED RECORD 
Quality: SIGNEDBYTE; {1 4£ received image was acceptable} 
END; 
pTFORcveEnd = “TFORcveEnd; 


{Return Data} 
{NIL} 


(Result Data} 
TERReveEnd = TFGenResult; {result of call} 
PTFRReveEnd = *TFRReveEnd; 


{== TransmitPacket Aes nee eee eee eee ess eens eee SEs Es= } 
{Command Data} 

TFOXmitPkt = FLineRec; 

pTFOXmitPkt = *TFOXmitPkt; 


{Return Data} 
{NIL} 


(Result Data} 
TFERXmitPkt = TFGenResult; {result of call} 
pTFRXmitekt = “TERXmitPkt; 


is= ReceivePacket emenscececeesceescesaesssseessSeese ss Sesessssezssess==} 
(Command Data) 
{NIL} 
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(Return Data} 
TFIRcvePkt = PACKED RECORD 


Result: SIGNEDBYTE; {result of the call} 

fill: SIGNEDBYTE; {fill} 

Length: INTEGER; {length of the buffer} 

Data: BufPtr; {pointer to buffer to receive data} 
END; 


pTFiRevePkt = “TFIRevePkt; 


{Result Data} 
TERRcvePkt = TFGenResult; {result of call} 
pTFRRevePkt = “TFRRevePkt; 


(== Disconnect =ss-seaeesseeeneseesseseeee eee esse ses ees e sess sees esses ) 


(Command Data} 
{NIL} 


{Return Data} 
(NIL? 


{Result Data} 
TFRDisconnect = TFGenResult; {result of call} 
pTFRDisconnect = “TFRDisconnect; 


: 


(== GetRegister SRR ESR AR eee eee EES esses eee eE ESSE sesEessssssoescens } 


s 


{Command Data} 
TFOGetReg = PACKED RECORD 
Register: SIGNEDBYTE; {register number} 
END; 
pTFOGetReg = “TFOGetReg: 


{Return Data} 
TFIGetReg = PACKED RECORD 


Result: SIGNEDBYTE; {result of the call} 

fill: SIGNEDBYTE; {filler} 

Value: INTEGER; {value in the register} 
END; 


pTiFiIGetReg = “TFIGetReg; 


{Result Data} 
TFRGetReg = PACKED RECORD 


Result: SIGNEDBYTE; {result of the call} 

fill: SIGNEDBYTE; {filler} 

Value: INTEGER; {value in the register} 
END; 


pIFRGetReg = “TFRGetReg; 


{== SetRegister sassseesansesessenaaeweeeee sees seen ese ee S SES sseseSSsssss } 


{Command Data} 
TFOSetReg = PACKED RECORD 


Register: SIGNEDBYTE; {register number} 
fill: SIGNEDBYTE; {filler} 
Value: INTEGER; {value in the register} 


END: 
pTFOSetReg = “TFOSetReg; 


{Return Data} 
TEISetReg = TFGenResult; 
- pTFISetReg = “*TFISetReg; 


{Result Data} 
TFRSetReg = TFGenResult; 
PTFRSetReg = “TFRSetReg; 


{== Reset We ESSERE SERS ARREST ASSESS SEE EERE EES ) 


{Command Data} 


Page 9 


9/23/87 3:12 PM HD:MPW:Faxing:FxCode:FaxIntf£.p 
{NIL) 


(Return Data} 
{NIL} 


(Result Data} 


(NIL} 
(== Cancel sacessecaeasseseseneaeacsasesesssssssnssscsssse2es2222222=25-2} 
(Command Data} 

(NIL} 


{Return Data} 
(NIL) 


{Result Data} 
{NIL} 


(== Version =s2=scss2sc2ems222 4s a5 ESE S552 4 232858 SABHA AAT ASS Ss } 
{Command Data} 
{NIL} 


{Return Data} 
TFIVersion = RECORD 


Result: SIGNEDBYTE; {status info} 

Fill: SIGNEDBYTE; 

Version: INTEGER; {currently executing command} 
END; 


pTtFiversion = *TFIVersion; 


(Result Data} 
TFRVersion = RECORD 


Result; SIGNEDBYTE; {status info} 

Fill: SIGNEDBYTE; 

Version: INTEGER; {currently executing command} 
END; 


pIFRVersion = *TFRVersion; 


{== GetResult SESS SPCR SS Sheek aes Ae eee ASR BEET sss= === } 
{Command Data} 
{NIL} 


(Return Data} 
TFIResult = TFGenResult; {result of call} 
pTFIResult = *TFIResult; 


(Result Data} 


{NIL} 


(s= P ickUp 20S See Eee eee ee eee ee eS ee eee Ae Z Ss 32 } 
{Command Data} 
{NIL} 


{Return Data} 
{NIL} 


{Result Data} 


TFRPickUp = TFGenResult; {result of call} 

PTFRPickUp = “TFRPickUp; 
{== HankUp SRSR aS SS rms sass sess sess sSSSee Sess sss SSS Sse ssSsrsesssss== } 
{Command Data} 


{NIL} 


Page 


10 


9/23/87 3:12 PM 


{Return Data) 


sult Data} 
FRHankUp = TFGenResult; 
pTFRHankUp = “TFRHankUp; 
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{result of call} 


{structure for passing fax commands to the low level driver} 


TFaxCmdRec = RECORD 
FaxCommand: INTEGER; 


hPacket: hFaxPacket; 
PPort: pSerialPair; 
pOutput: Per; 

pInput: Ptr: 
IdleProc: ProcPtr; 


END; 
pTFaxCmdRec = “TFaxCmdRec; 


{-e--- Fax options structures ---<-- were emer e—— enn rn nnn n nn ween ene } 
TFxSaveFile = RECORD 
sFname: Str2s5; 
sVRefNum: INTEGER; : é 
sVersion: INTEGER; 
END; 


{fax command to execute} 

{packet handle to use} 

{serial in / out reference info} 
{pointer to output structure} 

{pointer to input structure} 

{pointer to the user's idle procedure} 


PTFxSaveFile = “TFxSaveFile; 


TFxSaveAddrFile = CORD 
sFname: str255; 
sVRefNum: INTEGER; 
sWDDirID: LONGINT; 
sVezrsion: INTEGER: 

END; 


pTFxFileChain = “TFxfileChain; 


TFxFileChain = RECORD 


cFLink: pTFxFileChain; 
cFname: Str2s5; 
cVRefNum: INTEGER; 
eDirID: LONGINT; 

END; 


stri = STRING(1]; 
TOptsRec = RECORD 


Retries: INTEGER; 
ManualDial: BOOLEAN; 
ModeF lg: Strl; 
DialNumStr: PNumStr; 
TONum: TONumStr; 
StationID: TIDStr; 
DeSID: BOOLEAN; 


StationName: PNumStr; 
SaveFileRec: TFxSaveFile;: 


{retries} 

{Manual dial} 

{(t)one or (p)ulse string} 

{phone number string} 

{calling telephone number string) 
{text ID message imaged at page top} 
{boolean to image station id} 

{name of the applefax device} 


AddrBookRec: TFxSaveAddrFile; 
pFileChain: pTFxFileChain: {NIL if no files} 


END; 
TPOpts = “TOptsRec; 
THOpts = “TPOpts; 


{sAcas General I0 block structure s-<-----<------- St aa a oe aca stetatenell | 


TOParamBlockRec = RECORD 
{12 byte header used by the 
qLink: QElemPtr; (queue 


file and IO system} 


link in header} 


qType: INTEGER; (type byte for safety check} 
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soTrap: INTEGER; (Fs: the Trap} 
loCmdAddr: Ptr; {FS: address to dispatch to} 
{commen header to all variants} 
ioCompletion: ProcPtr; {completion routine addr (0 for 
synch calls) } 
foResult: OSErr; (result code} 
ioNamePtr: StringPtr; {ptr to Vol:FileName string) 
ioVRefNum: INTEGER; {volume refnum (DrvNum for Eject and 
MountVol) } 


toRefNum: INTEGER; {refNum for 1/0 operation} 
ieVersNum: SignedByte; (version number} 
ioPermssn: SignedByte; {Open: permissions (byte) } 


loMise: Ptr; (Rename: new name} 

{GetEOF, SerEoF: logical end of file) 

{Open: optional ptr to buffer} 

{SetFileType: new type} 

loBuffer: Ptr: {data buffer Ptr} 

ioReqCount: LONGINT; {requested byte count; also = 
LoNewDirID} 

fLoActCount: LONGINT; {actual byte count completed} 
loPasMode: INTEGER; (initial file Positioning) 
loPosOffsec: LONGINT; (file Position offset} 


one to write into code space. PAC / 07-APR~87} 


{variables used for fax packet xmission} 
TFxPack = RECORD 
{Position equates for FaxCmdout variables} 


VSCCIO: TOParamBlockRec; {general I0 Param block} 

{VSCCIO: ARRAY (0..24] of INTEGER; } {general IO param block} 
VidlePtr: ProcPtr; (pointer to the idle procedure} 
VPktPtr: PFaxPacket; {pointer to fax Packet to use for xmit } 
VPortPair: PSerialPair; {ptr to the serial port info to use} 
VPLOffset: INTEGER; {ptr list offset to next bfr to xmit} 
VIOPhase: INTEGER; {current state in the protocol} 
VRetries: INTEGER; {number of retries to Perform} 

VLength: INTEGER; {ptr to receive total len of the data} 
VTimeOut: LONGINT; (Number of ticks timeout allowed} . 


{Pointer list equates} 


VOutPtrs; Ptr; {pointer to output ptr list} 
VInPtrs: Ptr; {pointer to input ptr list} 
VNumOuts: INTEGER; {number of output elements in the list} 
VNumiIns: INTEGER; {number of input elements in the list} 


{control response buffer} 

VCRBuf: INTEGER; {packet responce buffer} 
END; 
PTFxPack = “TF xPack; 


(*TMTask = RECORD 


qLink: PTR; 

qType: INTEGER; 

tmAddr: ProcPtr; 

tmCount: LONGINT; 
“END; *) 


{variables used for fax line xmission} 
TExDump = RECORD 
{Routine Parameters for InitfaxDump} 
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(VP LandBMap: TPBitMap; } {landscape bitmap struct} 

VPNumBfrs: LONGINT; {number of line bfrs} “a 
VPSfrSize: LONGINT; {size of the line bfrs)} ( 
VPLineList: PTR; {ptr to list of line bfrs} 

VPCapable: pSFIRec; {ptr capabilities structure} 

VPSCCPair: pSerialPair; {ptr to serial pair} 


ivariables used by FaxDumpBand} 
(Flags, etc.} 
VXPrimed: INTEGER; {timer routine has been primed} 


{IO and band queue management pointers} 


VXPBBase: PTR: {ptr to the top of the PBs} 
VXIOQBase: PTR; {ptr to top of IO queue} 

VXIOQPtr: PTR; {ptr to lst queue element} 
VXBdQOPtr: PTR; {ptr to top of band queue} 


{Interupt task entry} 


UXTimeTask: TMTask; {time manager task record} 
VXTimeFix: LONGINT; {time mgr kills this for some reason} 
ENO; 


pTtFxDump = “TE xDump; 


{variables used by the low level driver} P 
TFxDrvr = RECORD 


fPrVars: TPPrVars; : . 
fhPrinc: THPrint;: < 
fPrPort: TPPrPort: = 
iVPos: INTEGER; 


BusyDlg: DialogPtr; 
HOptions: THOpts; 


OurFxDev: BOOLEAN; 

OurkPrint: BOOLEAN; ( 
DoIt: BOOLEAN; 

END; 


pTFxDrvr = “TExOrver;: 


{All cf the fax vars are pointed to by this chunk} 
TFPxDev =» RECORD 


FxPackVars: TExPack; {fax packet variables} 

FxDumpVars: TFxDump; {fax line dump variables} 

pFxDrvrVars: pT&xDrvr; {low level drvr variables} 
END; 


pIFxDev = “TExDev; 


{ The PicFile State Object } 
TPfState = RECORD 


hPic: PicHandle; {The current Pic} 

iDecPage: Integer; {The current (DOC, not PrFile!) page.} 

hFileName: Handle; {Default file name resource handle} 

PfHeader: TP fHeader: {The PicFile's header} 

iPfRefNum: Integer; {The PicFile's refnum} 

lPicBytes: LongInt; (The current pic's size. Zeroed in PfOpenPage, incremented ia 


PfOut, used in PfClosePage to set directory entry for next page.} 


iBuf: Integer; {IO Buffer} 

bBuf: ARRAY(1..iFxIOB]LkBytes] OF SignedByte; 

rDirty: rect: {DC 10/16/84} 

hPicSave: QDHandle;: {DC 10/16/84} ois 
appClip, ( 
QDClip: rgnHandile; {DC 11/12/84} 

rFrame: rect: {DC 1/7/85} 


{PAC / 08-JUL-87} 
HOptions: THOpts; 


9/23/87 3:12 PM 


StatDlg: DialogPtr; 
SaveGhost: DialogPtr; 
DoErrDlgs: BOOLEAN; 


DoStatusDigs: BOOLEAN; 
fTheyAllocated: BOOLEAN; 
END; 
TePfState = “TPf£State; 
THPfState = “TPPfState; 
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{temp ptr to the status dialog} 

‘variable to save the ghost} 

{do the error dialogs} 

{do the status messages} 

{this structure was allocated externally} 


{The fax's use of the PrVars} 


TFxVars = RECORD 


iPrErr: Integer; 
bDocLoop: SignedByte; 
bUserl: SignedByte; 
nPfState: THPfState; 
pFxDev: pTF&xDev; 
user2: TLONG; 

ND; 


36 


PrxVars = *TExVars; 


IMPLEMENTATION 


END. 


(Current print error. Set to iPrAbort to abort printing.} 
{The Doc style: Draft, Spool, .., and ..} 
{Currently use low 3 bits; the upper 5 are for flags. 
Bit 2 is fNewRun.} 
{Spares used by the print code} 
{lUserl: The State handle.} 
{pointer to our fax packet variables} 
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Appendix C 


Sample Procedures for Receiving a Fax File 


To receive fax files, your application must first detect the phone ringing and then determine 
if the caller is a fax machine by inspecting the capabilities returned by the FaxAnswer cal. 
If it is a fax machine, you can call the first procedure below to set up the files for reception. 
The next procedure actually receives the data, writing out the temp file in the correct packet 
format. In your own implementation ydu should be checking for errors and responding 
accordingly. 


Procedure: RecvFaxFile (theStationID, theCapabilities); 


VAR 
aTempFile: TFxSaveFile; 
aFinalFile: TFxSaveFile; 
BEGIN 


{make the temp file and open it} 
anError := Create ('TheRecvFile', tempVRefNum, 'YNOT’, 'TEMP’) ; 
anError := FSOpen('TheRecvFile', tempVRefNum, itsRefNum) ; 


{get the data} 
recvError := RecvFaxFileData(theStationID, theCapabilities, 
’ itsRefNum) ; 


{close the file} 
FSClose (itsRefNum) ; 


{make the final fax file} 
{Note: the creator and file type for the file} 
anError := Create('TheFaxFile', faxVRefNum, ‘FFAX', '‘FFIL'); 


{make the conversion} 

{set up the file records} 
aTempFile.sFname := 'TheRecvFile'; 
aTempFile.sVRefNum := tempVRefNum; 
aTempFile.sVersion := 0; 


aFinalFile.sFname 'TheFaxFile'; 
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aFinalFile.sVRefNum := faxVRefNum; ( 
aFinalFile.sVersion := 0; 


{do the conversion} 
anError := FxConvertFile (pTFxSaveFrile (@aTempFile), 
pTFxSaveFile (@aFinalFile) ); 


{trash the temp File} 
anError := FSDelete('TheRecvrile', tempVRefNum) ; 


END; 


FUNCTION: TFaxModem.RecvFaxFileData(theStationID: IDNumSrr, theCapabilities: 
SFiRec; tempFile: INTEGER): OSErr, 


CONST 
kCapabilities = 0; 
kStationID = 1; 
kPageStart = 2; 
kPageData . = 3; . 
kLastPage = 4; : 
TYPE 
aPacket = RECORD 
theType: INTEGER; eC 
theLength: INTEGER; 
END; 
VAR 
thePacket: aPacket; 
numBytes: INTEGER; 
numToWrite: LONGINT; 
numToAdd: INTEGER; 
anError: INTEGER; 
outRec: TFORcveBfr; 
inRec: TFIRcveBfr; 
morePages: INTEGER; 
fileBuffer: TFileBuffer; 
BEGIN 


{set up ptr for data} 
inRec.Data := @MyBuffer; 


{write out capabilities} 
thePacket.theType := kCapabilities; 
thePacket.theLength := SIZEOF(SFIRec) ; 
numToWrite := SIZEOF(aPacket); 


anError := FSWrite(tempFile, numToWrite, @thePacket); 
numToWrite := SIZEOF(SFIRec); 7 
anError := FSWrite(tempFile, numToWrite, @theCapabilities); ( 
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{write out station ID string} 


thePacket .theType >= kStationID; 

thePacket.theLength := LENGTH (theStationID) ; 

humToWrite := SIZEOF(aPacket) ; 

anError := FSWrite (tempFile, numToWrite, @thePacket); 
numToWrite := LENGTH (theStationID) ; 

anError := FSWrite (tempFile, numToWrite, @theStationID); 


{set up modem to begin receiving the pages} 
WHILE (FaxReceive = 0) DO 

BEGIN 

inRec.Done := 0; 


{get the data} 
thePacket.theType := kPageStart; 


{capture all the data for a page} 

REPEAT {UNTIL inRec.Done = 1} 

BEGIN 

anError := ReceiveBuffer (1024, inRec) ; 

{write data out to file} 

thePacket.theLength := inRec.Length; 

numToAdd ' 3s SIZEOF (aPacket) ; ; . 
numTowWrite := SIZEOF (aPacket) ; ~ 
IF thePacket.theLength > 0 THEN 

anError := FSWrite(tempFile, numToWrite, @thePacket); 
numToAdd := inRec.Length; 

numToWrite := inRec.Length; 

IF thePacket.theLength > 0 THEN 

anError := FSWrite(tempFile, numToWrite, inRec.Data); 
thePacket.theType := kPageData; 

END 


UNTIL inRec.Done = 1; 
anError:= ReceiveEnd(1); {always return 1 for quality OK} 
IF anError <> noErr THEN {no more pages to receive} 


BEGIN 

{put out end of page stuff} 

thePacket .theType := kLastPage; 

thePacket.theLength := 0; 

numToWrite := SIZEOF (aPacket) ; 

anError := FPSWrite(tempFile, numToWrite, @thePacket) 
RecvFaxFileData := anError; 

EXIT (RecvFaxFileData) ; 

END; 

{set up for next page} 

thePacket .theType >= kPageStart; 
thePacket.theLength := 0; 

numToWrite := SIZEOF (aPacket) ; 

anError i= FSWrite(tempFile, numToWrite, @thePacket); 


END; {WHILE (FaxReceive = 0) } 
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END; 


{write out the end of file packet} 


thePacket.theType := kLastPage; 
thePacket.theLength := 0; 
numToWrite := SIZEOF (aPacket) ; 


anError := FSWrite(tempFile, numToWrite, @thePacket); 


{return any errors} 
RecvFaxFileData := anError; 
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